@jmruthers/pace-core 0.6.9 → 0.6.11

package/dist/chunk-J2KQK6DG.js

@@ -0,0 +1,2159 @@
+import { EventServiceContext } from './chunk-4R3T5ENU.js';
+import { clearPalette, parseAndNormalizeEventColours, applyPalette } from './chunk-D6BMFMQZ.js';
+import { assertAppId } from './chunk-4SXLQIZO.js';
+import { fetchPlaceDetails, createAddressFromPlaceResult, getAddressByPlaceId, fetchPlaceAutocomplete, setOrganisationContext } from './chunk-XPFVT3GN.js';
+import { createLogger, logger } from './chunk-BTHN5MKC.js';
+import { ok, err } from './chunk-44CNXN4P.js';
+import { useState, useEffect, useCallback, useMemo, useRef, useContext } from 'react';
+import { useLocation } from 'react-router-dom';
+
+function useDebounce(value, delay) {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+  useEffect(() => {
+    const handler = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+    return () => {
+      clearTimeout(handler);
+    };
+  }, [value, delay]);
+  return debouncedValue;
+}
+var log = createLogger("useQueryCache");
+var queryCache = /* @__PURE__ */ new Map();
+var CLEANUP_INTERVAL_MS = 5 * 60 * 1e3;
+var cleanupTimer = null;
+function runCacheCleanup() {
+  const now = Date.now();
+  const expiredKeys = [];
+  queryCache.forEach((entry, key) => {
+    if (entry.expiresAt <= now) {
+      expiredKeys.push(key);
+    }
+  });
+  expiredKeys.forEach((key) => {
+    queryCache.delete(key);
+    log.debug(`Removed expired query from cache: ${key}`);
+  });
+}
+if (typeof window !== "undefined" && !cleanupTimer) {
+  cleanupTimer = setInterval(runCacheCleanup, CLEANUP_INTERVAL_MS);
+  window.addEventListener("beforeunload", () => {
+    if (cleanupTimer) {
+      clearInterval(cleanupTimer);
+      cleanupTimer = null;
+    }
+  });
+}
+function cleanupQueryCache() {
+  if (cleanupTimer) {
+    clearInterval(cleanupTimer);
+    cleanupTimer = null;
+  }
+}
+function useQueryCache(_supabase) {
+  const getCachedQuery = useCallback(async (table, filterKey, filterValue, fetchFn, options = {}) => {
+    const { ttl = 300, enabled = true } = options;
+    const cacheKey = `${table}:${filterKey}:${filterValue}`;
+    const now = Date.now();
+    if (!enabled) {
+      return fetchFn();
+    }
+    const cached = queryCache.get(cacheKey);
+    if (cached) {
+      if (cached.expiresAt > now && cached.data !== void 0) {
+        log.debug(`Cache hit for query: ${cacheKey}`);
+        return cached.data;
+      }
+      if (cached.promise) {
+        log.debug(`Waiting for in-flight request: ${cacheKey}`);
+        return cached.promise;
+      }
+    }
+    log.debug(`Cache miss for query: ${cacheKey}, fetching...`);
+    const fetchPromise = fetchFn();
+    queryCache.set(cacheKey, {
+      data: void 0,
+      expiresAt: now + ttl * 1e3,
+      promise: fetchPromise
+    });
+    try {
+      const data = await fetchPromise;
+      queryCache.set(cacheKey, {
+        data,
+        expiresAt: now + ttl * 1e3
+      });
+      log.debug(`Cached query result: ${cacheKey}, expires in ${ttl}s`);
+      return data;
+    } catch (error) {
+      queryCache.delete(cacheKey);
+      log.error(`Query failed for ${cacheKey}:`, error);
+      throw error;
+    }
+  }, []);
+  const invalidateQuery = useCallback((table, filterKey, filterValue) => {
+    const cacheKey = `${table}:${filterKey}:${filterValue}`;
+    queryCache.delete(cacheKey);
+    log.debug(`Invalidated query cache: ${cacheKey}`);
+  }, []);
+  const clearCache = useCallback(() => {
+    queryCache.clear();
+    log.debug("Cleared all query cache entries.");
+  }, []);
+  const getCacheStats = useCallback(() => {
+    return {
+      size: queryCache.size,
+      keys: Array.from(queryCache.keys())
+    };
+  }, []);
+  return {
+    getCachedQuery,
+    invalidateQuery,
+    clearCache,
+    getCacheStats
+  };
+}
+var queryCacheHelpers = {
+  /**
+   * Cache core_person queries by user_id
+   * TTL: 5 minutes
+   */
+  pacePersonByUserId: (supabase, userId, fetchFn) => {
+    const cacheKey = `core_person:user_id:${userId}`;
+    const now = Date.now();
+    const ttl = 300 * 1e3;
+    const cached = queryCache.get(cacheKey);
+    if (cached && cached.expiresAt > now && cached.data !== void 0) {
+      return Promise.resolve(cached.data);
+    }
+    if (cached?.promise) {
+      return cached.promise;
+    }
+    const promise = fetchFn();
+    queryCache.set(cacheKey, {
+      data: void 0,
+      expiresAt: now + ttl,
+      promise
+    });
+    promise.then((data) => {
+      queryCache.set(cacheKey, { data, expiresAt: now + ttl });
+    }).catch(() => {
+      queryCache.delete(cacheKey);
+    });
+    return promise;
+  },
+  /**
+   * Cache core_member queries by person_id
+   * TTL: 5 minutes
+   */
+  paceMemberByPersonId: (supabase, personId, fetchFn) => {
+    const cacheKey = `core_member:person_id:${personId}`;
+    const now = Date.now();
+    const ttl = 300 * 1e3;
+    const cached = queryCache.get(cacheKey);
+    if (cached && cached.expiresAt > now && cached.data !== void 0) {
+      return Promise.resolve(cached.data);
+    }
+    if (cached?.promise) {
+      return cached.promise;
+    }
+    const promise = fetchFn();
+    queryCache.set(cacheKey, {
+      data: void 0,
+      expiresAt: now + ttl,
+      promise
+    });
+    promise.then((data) => {
+      queryCache.set(cacheKey, { data, expiresAt: now + ttl });
+    }).catch(() => {
+      queryCache.delete(cacheKey);
+    });
+    return promise;
+  },
+  /**
+   * Cache rbac_app_pages queries by app_id
+   * TTL: 15 minutes (app pages are relatively static)
+   */
+  rbacAppPagesByAppId: (supabase, appId, fetchFn) => {
+    const cacheKey = `rbac_app_pages:app_id:${appId}`;
+    const now = Date.now();
+    const ttl = 15 * 60 * 1e3;
+    const cached = queryCache.get(cacheKey);
+    if (cached && cached.expiresAt > now && cached.data !== void 0) {
+      return Promise.resolve(cached.data);
+    }
+    if (cached?.promise) {
+      return cached.promise;
+    }
+    const promise = fetchFn();
+    queryCache.set(cacheKey, {
+      data: void 0,
+      expiresAt: now + ttl,
+      promise
+    });
+    promise.then((data) => {
+      queryCache.set(cacheKey, { data, expiresAt: now + ttl });
+    }).catch(() => {
+      queryCache.delete(cacheKey);
+    });
+    return promise;
+  }
+};
+async function fetchSuggestionsForInput(debouncedInput, apiKey, memoizedAutocompleteOptions, cacheEnabled, cacheTTLAutocomplete, getCachedQuery, isCancelledRef, setters) {
+  try {
+    let result;
+    if (cacheEnabled) {
+      result = await getCachedQuery(
+        "google-places-autocomplete",
+        "query",
+        debouncedInput,
+        async () => {
+          if (isCancelledRef.current) {
+            throw new Error("Request cancelled");
+          }
+          return fetchPlaceAutocomplete(debouncedInput, apiKey, memoizedAutocompleteOptions);
+        },
+        { ttl: cacheTTLAutocomplete, enabled: true }
+      );
+    } else {
+      result = await fetchPlaceAutocomplete(debouncedInput, apiKey, memoizedAutocompleteOptions);
+    }
+    if (isCancelledRef.current) return;
+    if (!result.ok) {
+      setters.setError(new Error(result.error.message));
+      setters.setSuggestions([]);
+      setters.setIsLoading(false);
+      return;
+    }
+    setters.setSuggestions(result.data);
+    setters.setIsLoading(false);
+  } catch (err2) {
+    if (isCancelledRef.current || err2 instanceof Error && err2.message === "Request cancelled") {
+      return;
+    }
+    const error = err2 instanceof Error ? err2 : new Error("Failed to fetch autocomplete suggestions");
+    setters.setError(error);
+    setters.setSuggestions([]);
+    setters.setIsLoading(false);
+  }
+}
+function useAddressAutocomplete(apiKey, inputValue, options = {}) {
+  const {
+    debounceDelay = 300,
+    cacheEnabled = true,
+    cacheTTL = {
+      autocomplete: 3600,
+      // 1 hour
+      placeDetails: 86400
+      // 24 hours
+    },
+    autocompleteOptions
+  } = options;
+  const [suggestions, setSuggestions] = useState([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const debouncedInput = useDebounce(inputValue, debounceDelay);
+  const { getCachedQuery } = useQueryCache();
+  const memoizedAutocompleteOptions = useMemo(() => {
+    if (!autocompleteOptions) {
+      return void 0;
+    }
+    return {
+      components: autocompleteOptions.components,
+      location: autocompleteOptions.location,
+      radius: autocompleteOptions.radius,
+      language: autocompleteOptions.language,
+      types: autocompleteOptions.types
+    };
+  }, [
+    autocompleteOptions
+  ]);
+  useEffect(() => {
+    if (!debouncedInput.trim()) {
+      setSuggestions([]);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+    if (!apiKey) {
+      setError(new Error("Google Places API key is required"));
+      return;
+    }
+    setIsLoading(true);
+    setError(null);
+    const isCancelledRef = { current: false };
+    fetchSuggestionsForInput(
+      debouncedInput,
+      apiKey,
+      memoizedAutocompleteOptions,
+      cacheEnabled,
+      cacheTTL.autocomplete ?? 3600,
+      getCachedQuery,
+      isCancelledRef,
+      { setSuggestions, setError, setIsLoading }
+    );
+    return () => {
+      isCancelledRef.current = true;
+    };
+  }, [debouncedInput, apiKey, cacheEnabled, cacheTTL.autocomplete, memoizedAutocompleteOptions, getCachedQuery]);
+  const selectAddress = useCallback(
+    async (placeId) => {
+      if (!placeId || !apiKey) {
+        return null;
+      }
+      setIsLoading(true);
+      setError(null);
+      try {
+        let placeResult;
+        if (cacheEnabled) {
+          placeResult = await getCachedQuery(
+            "google-places-details",
+            "place_id",
+            placeId,
+            async () => fetchPlaceDetails(placeId, apiKey),
+            { ttl: cacheTTL.placeDetails, enabled: true }
+          );
+        } else {
+          placeResult = await fetchPlaceDetails(placeId, apiKey);
+        }
+        if (!placeResult.ok) {
+          setError(new Error(placeResult.error.message));
+          setIsLoading(false);
+          return null;
+        }
+        const parsedAddress = createAddressFromPlaceResult(placeResult.data);
+        setIsLoading(false);
+        return parsedAddress;
+      } catch (err2) {
+        const error2 = err2 instanceof Error ? err2 : new Error("Failed to fetch place details");
+        setError(error2);
+        setIsLoading(false);
+        return null;
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [apiKey, cacheEnabled, cacheTTL.placeDetails]
+  );
+  const getAddressByPlaceIdFn = useCallback(
+    async (placeId) => {
+      if (!placeId || !apiKey) {
+        return null;
+      }
+      try {
+        let result;
+        if (cacheEnabled) {
+          result = await getCachedQuery(
+            "google-places-details",
+            "place_id",
+            placeId,
+            async () => getAddressByPlaceId(placeId, apiKey),
+            { ttl: cacheTTL.placeDetails, enabled: true }
+          );
+        } else {
+          result = await getAddressByPlaceId(placeId, apiKey);
+        }
+        if (!result.ok) {
+          setError(new Error(result.error.message));
+          return null;
+        }
+        return result.data;
+      } catch (err2) {
+        const error2 = err2 instanceof Error ? err2 : new Error("Failed to get address by place_id");
+        setError(error2);
+        return null;
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [apiKey, cacheEnabled, cacheTTL.placeDetails]
+  );
+  const clearSuggestions = useCallback(() => {
+    setSuggestions([]);
+    setError(null);
+  }, []);
+  return {
+    suggestions,
+    isLoading,
+    error,
+    selectAddress,
+    getAddressByPlaceId: getAddressByPlaceIdFn,
+    clearSuggestions
+  };
+}
+
+// src/utils/storage/config.ts
+var FILE_SIZE_LIMITS = {
+  // Images
+  "image/jpeg": 5 * 1024 * 1024,
+  // 5MB
+  "image/png": 5 * 1024 * 1024,
+  // 5MB
+  "image/gif": 10 * 1024 * 1024,
+  // 10MB (for animations)
+  "image/webp": 5 * 1024 * 1024,
+  // 5MB
+  "image/svg+xml": 1 * 1024 * 1024,
+  // 1MB (vector graphics)
+  // Documents
+  "application/pdf": 50 * 1024 * 1024,
+  // 50MB
+  "application/msword": 25 * 1024 * 1024,
+  // 25MB
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document": 25 * 1024 * 1024,
+  // 25MB
+  "application/vnd.ms-excel": 25 * 1024 * 1024,
+  // 25MB
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": 25 * 1024 * 1024,
+  // 25MB
+  // Archives
+  "application/zip": 100 * 1024 * 1024,
+  // 100MB
+  "application/x-rar-compressed": 100 * 1024 * 1024,
+  // 100MB
+  // Text files
+  "text/plain": 1 * 1024 * 1024,
+  // 1MB
+  "text/csv": 10 * 1024 * 1024,
+  // 10MB
+  "application/json": 10 * 1024 * 1024
+  // 10MB
+};
+var DEFAULT_FILE_SIZE_LIMIT = 10 * 1024 * 1024;
+var APP_PATH_MAPPING = {
+  "PACE": "event_logos",
+  "TRAC": "trac_accommodation",
+  // Default category for TRAC files
+  "MEDI": "documents",
+  "CAKE": "documents"
+};
+var STORAGE_CONFIG = {
+  bucketName: "files",
+  fileSizeLimits: FILE_SIZE_LIMITS,
+  defaultFileSizeLimit: DEFAULT_FILE_SIZE_LIMIT
+};
+function getFileSizeLimit(mimeType) {
+  return STORAGE_CONFIG.fileSizeLimits[mimeType] || STORAGE_CONFIG.defaultFileSizeLimit;
+}
+function getBucketName(isPublic) {
+  return isPublic ? "public-files" : "files";
+}
+function validateFileSize(file) {
+  const limit = getFileSizeLimit(file.type);
+  if (file.size > limit) {
+    const limitMB = Math.round(limit / (1024 * 1024));
+    const fileMB = Math.round(file.size / (1024 * 1024));
+    return {
+      isValid: false,
+      error: `File size (${fileMB}MB) exceeds limit (${limitMB}MB) for ${file.type}`
+    };
+  }
+  return { isValid: true };
+}
+
+// src/utils/storage/helpers.ts
+var log2 = createLogger("StorageHelpers");
+function generateFilePath(options, fileName) {
+  const { orgId, userId, isPublic = false, customPath } = options;
+  if (!orgId && !userId) {
+    throw new Error("Either orgId or userId is required for file path generation");
+  }
+  const basePath = orgId ? orgId : `users/${userId}`;
+  if (isPublic) {
+    if (customPath) {
+      return `${basePath}/${customPath}/${fileName}`;
+    }
+    return `${basePath}/public/${fileName}`;
+  }
+  if (customPath) {
+    return `${basePath}/${customPath}/${fileName}`;
+  }
+  const pathFolder = customPath || "files";
+  return `${basePath}/${pathFolder}/${fileName}`;
+}
+function generateUniqueFileName(originalName) {
+  const timestamp = Date.now();
+  const uuid = crypto.randomUUID();
+  const extension = originalName.split(".").pop() || "";
+  let baseName = originalName.replace(/\.[^/.]+$/, "");
+  baseName = baseName.trim().replace(/\s+/g, "_").replace(/[<>:"/\\|?*]/g, "").replace(/\.\./g, "").replace(/^\.+|\.+$/g, "").substring(0, 200);
+  if (!extension || extension === originalName) {
+    return `${timestamp}-${uuid}-${baseName}`;
+  }
+  return `${timestamp}-${uuid}-${baseName}.${extension}`;
+}
+async function extractFileMetadata(file, options, uploadedBy) {
+  try {
+    const metadata = {
+      mimeType: file.type,
+      size: file.size,
+      ...options.orgId && { orgId: options.orgId },
+      ...options.userId && { userId: options.userId },
+      appName: options.appName || "pace-core",
+      uploadedBy,
+      uploadedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      tags: options.tags || [],
+      isPublic: options.isPublic || false,
+      customMetadata: options.metadata || {}
+    };
+    if (file.type.startsWith("image/")) {
+      try {
+        const dimensions = await getImageDimensions(file);
+        metadata.width = dimensions.width;
+        metadata.height = dimensions.height;
+      } catch (_error) {
+      }
+    }
+    try {
+      metadata.hash = await generateFileHash(file);
+    } catch (_error) {
+    }
+    return ok(metadata);
+  } catch (error) {
+    return err({
+      code: "EXTRACT_METADATA_FAILED",
+      message: error instanceof Error ? error.message : "Unknown error"
+    });
+  }
+}
+async function getImageDimensions(file) {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    const url = URL.createObjectURL(file);
+    img.onload = () => {
+      URL.revokeObjectURL(url);
+      resolve({ width: img.width, height: img.height });
+    };
+    img.onerror = () => {
+      URL.revokeObjectURL(url);
+      reject(new Error("Could not load image"));
+    };
+    img.src = url;
+  });
+}
+async function generateFileHash(file) {
+  const buffer = await file.arrayBuffer();
+  const hashBuffer = await crypto.subtle.digest("SHA-256", buffer);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  const hashHex = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+  return `sha256:${hashHex}`;
+}
+async function ensureFolderExists(supabase, folderPath, bucketName) {
+  try {
+    const { data, error } = await supabase.storage.from(bucketName).list(folderPath, {
+      limit: 1
+    });
+    if (!error) {
+      return true;
+    }
+    const placeholderPath = `${folderPath}/.keep`;
+    const placeholderBlob = new Blob([""], { type: "text/plain" });
+    const placeholderFile = new File([placeholderBlob], ".keep", { type: "text/plain" });
+    const { error: uploadError } = await supabase.storage.from(bucketName).upload(placeholderPath, placeholderFile, {
+      cacheControl: "3600",
+      upsert: true,
+      // Use upsert to avoid errors if file already exists
+      contentType: "text/plain"
+    });
+    if (uploadError) {
+      log2.debug(`Could not create folder placeholder (will be created on upload): ${uploadError.message}`);
+      return true;
+    }
+    return true;
+  } catch (error) {
+    log2.debug(`Folder creation exception (will be created on upload): ${error instanceof Error ? error.message : "Unknown error"}`);
+    return true;
+  }
+}
+async function uploadFile(supabase, file, options) {
+  try {
+    const sizeValidation = validateFileSize(file);
+    if (!sizeValidation.isValid) {
+      return err({ code: "FILE_SIZE_INVALID", message: sizeValidation.error ?? "File size validation failed" });
+    }
+    const uniqueFileName = generateUniqueFileName(file.name);
+    const filePath = generateFilePath(options, uniqueFileName);
+    const folderPath = filePath.substring(0, filePath.lastIndexOf("/"));
+    const metadataResult = await extractFileMetadata(file, options, "current-user");
+    if (!metadataResult.ok) {
+      return err(metadataResult.error);
+    }
+    const metadata = metadataResult.data;
+    const bucketName = getBucketName(options.isPublic || false);
+    await ensureFolderExists(supabase, folderPath, bucketName);
+    const { error } = await supabase.storage.from(bucketName).upload(filePath, file, {
+      cacheControl: "3600",
+      upsert: false,
+      contentType: file.type
+    });
+    if (error) {
+      return err({ code: "UPLOAD_FAILED", message: error.message });
+    }
+    let publicUrl;
+    if (options.isPublic) {
+      const { data: urlData } = supabase.storage.from(bucketName).getPublicUrl(filePath);
+      publicUrl = urlData.publicUrl;
+    }
+    return ok({ path: filePath, publicUrl, metadata });
+  } catch (error) {
+    return err({
+      code: "UPLOAD_FAILED",
+      message: error instanceof Error ? error.message : "Unknown error"
+    });
+  }
+}
+function getPublicUrl(supabase, path, isPublic = true) {
+  if (!supabase) {
+    throw new Error("Supabase client is required to generate a public URL");
+  }
+  if (!path || typeof path !== "string") {
+    throw new Error("A valid storage path is required to generate a public URL");
+  }
+  if (/^https?:\/\//i.test(path)) {
+    return path;
+  }
+  const normalisedPath = path.trim().replace(/^\/+/, "");
+  if (!normalisedPath) {
+    throw new Error("Storage path cannot be empty after normalisation");
+  }
+  const { bucketNameFromPath, storagePath } = resolveBucketHint(normalisedPath);
+  const bucketName = bucketNameFromPath || getBucketName(isPublic);
+  const { data } = supabase.storage.from(bucketName).getPublicUrl(storagePath);
+  return data.publicUrl;
+}
+function resolveBucketHint(pathWithPotentialBucket) {
+  const BUCKET_NAME_PATTERN = /^[a-z0-9][a-z0-9-_\.]{1,62}$/i;
+  const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  const KNOWN_BUCKET_NAMES = /* @__PURE__ */ new Set(["files", "public-files"]);
+  const trimmedPath = pathWithPotentialBucket.trim();
+  if (!trimmedPath) {
+    throw new Error("Storage path cannot be empty after normalisation");
+  }
+  const doubleColonIndex = trimmedPath.indexOf("::");
+  if (doubleColonIndex > 0) {
+    const potentialBucket = trimmedPath.slice(0, doubleColonIndex).trim();
+    const remainingPath = trimmedPath.slice(doubleColonIndex + 2).replace(/^\/+/, "");
+    if (potentialBucket && remainingPath && BUCKET_NAME_PATTERN.test(potentialBucket)) {
+      return {
+        bucketNameFromPath: potentialBucket,
+        storagePath: remainingPath
+      };
+    }
+  }
+  const firstSlashIndex = trimmedPath.indexOf("/");
+  if (firstSlashIndex > 0) {
+    const potentialBucket = trimmedPath.slice(0, firstSlashIndex).trim();
+    const remainingPath = trimmedPath.slice(firstSlashIndex + 1).replace(/^\/+/, "");
+    if (potentialBucket && remainingPath && BUCKET_NAME_PATTERN.test(potentialBucket) && !UUID_PATTERN.test(potentialBucket) && (KNOWN_BUCKET_NAMES.has(potentialBucket) || !potentialBucket.includes("-")) && !/^\d+$/.test(potentialBucket)) {
+      return {
+        bucketNameFromPath: potentialBucket,
+        storagePath: remainingPath
+      };
+    }
+  }
+  return {
+    bucketNameFromPath: null,
+    storagePath: trimmedPath
+  };
+}
+async function getSignedUrl(supabase, path, options) {
+  try {
+    const bucketName = getBucketName(false);
+    const { data, error } = await supabase.storage.from(bucketName).createSignedUrl(path, options.expiresIn || 3600);
+    if (error) {
+      log2.error("Failed to create signed URL:", error);
+      return err({ code: "SIGNED_URL_FAILED", message: error.message });
+    }
+    return ok({
+      url: data.signedUrl,
+      expiresAt: new Date(Date.now() + (options.expiresIn || 3600) * 1e3).toISOString()
+    });
+  } catch (error) {
+    log2.error("Failed to create signed URL:", error);
+    return err({
+      code: "SIGNED_URL_FAILED",
+      message: error instanceof Error ? error.message : "Unknown error"
+    });
+  }
+}
+var globalUrlCache = /* @__PURE__ */ new Map();
+var MAX_CACHE_SIZE = 500;
+function getCacheKey(fileId, filePath, isPublic) {
+  return `file-url:${fileId}:${isPublic ? "public" : "private"}`;
+}
+function cleanupUrlCache() {
+  const now = Date.now();
+  for (const [key, value] of globalUrlCache.entries()) {
+    if (value.expiresAt < now) {
+      globalUrlCache.delete(key);
+    }
+  }
+  if (globalUrlCache.size > MAX_CACHE_SIZE) {
+    const entries = Array.from(globalUrlCache.entries());
+    entries.sort((a, b) => a[1].expiresAt - b[1].expiresAt);
+    const toRemove = Math.floor(MAX_CACHE_SIZE * 0.2);
+    for (let i = 0; i < toRemove && i < entries.length; i++) {
+      globalUrlCache.delete(entries[i][0]);
+    }
+  }
+}
+async function generateFileUrlsBatch(supabase, fileReferences, options) {
+  try {
+    const urlMap = /* @__PURE__ */ new Map();
+    if (fileReferences.length === 0) {
+      return ok(urlMap);
+    }
+    const now = Date.now();
+    const ttl = (options.expiresIn || 3600) * 1e3;
+    const publicFiles = [];
+    const privateFiles = [];
+    const uncachedFiles = [];
+    for (const fileRef of fileReferences) {
+      const cacheKey = getCacheKey(fileRef.id, fileRef.file_path, fileRef.is_public);
+      const cached = globalUrlCache.get(cacheKey);
+      if (cached && cached.expiresAt > now) {
+        urlMap.set(fileRef.id, cached.url);
+        continue;
+      }
+      if (fileRef.is_public) {
+        publicFiles.push({ id: fileRef.id, file_path: fileRef.file_path });
+      } else {
+        privateFiles.push({ id: fileRef.id, file_path: fileRef.file_path });
+      }
+      uncachedFiles.push(fileRef);
+    }
+    for (const file of publicFiles) {
+      try {
+        const url = getPublicUrl(supabase, file.file_path, true);
+        if (url) {
+          urlMap.set(file.id, url);
+          const cacheKey = getCacheKey(file.id, file.file_path, true);
+          globalUrlCache.set(cacheKey, { url, expiresAt: now + ttl });
+        }
+      } catch (e) {
+        log2.error(`Failed to generate public URL for file ${file.id}:`, e);
+      }
+    }
+    if (privateFiles.length > 0) {
+      const signedUrlPromises = privateFiles.map(async (file) => {
+        const signedUrlResult = await getSignedUrl(supabase, file.file_path, {
+          appName: options.appName || "pace-core",
+          orgId: options.orgId,
+          expiresIn: options.expiresIn || 3600
+        });
+        const url = signedUrlResult.ok ? signedUrlResult.data.url : null;
+        if (url) {
+          const cacheKey = getCacheKey(file.id, file.file_path, false);
+          globalUrlCache.set(cacheKey, { url, expiresAt: now + ttl });
+        }
+        return { id: file.id, url };
+      });
+      const signedUrlResults = await Promise.all(signedUrlPromises);
+      for (const result of signedUrlResults) {
+        if (result.url) {
+          urlMap.set(result.id, result.url);
+        }
+      }
+    }
+    if (uncachedFiles.length > 0) {
+      cleanupUrlCache();
+    }
+    return ok(urlMap);
+  } catch (error) {
+    return err({
+      code: "BATCH_URLS_FAILED",
+      message: error instanceof Error ? error.message : "Unknown error"
+    });
+  }
+}
+async function deleteFile(supabase, path, isPublic = false) {
+  try {
+    const bucketName = getBucketName(isPublic);
+    const { error } = await supabase.storage.from(bucketName).remove([path]);
+    if (error) {
+      return err({ code: "DELETE_FAILED", message: error.message });
+    }
+    return ok(void 0);
+  } catch (error) {
+    return err({
+      code: "DELETE_FAILED",
+      message: error instanceof Error ? error.message : "Unknown error"
+    });
+  }
+}
+async function listFiles(supabase, options) {
+  try {
+    const bucketName = getBucketName(options.isPublic || false);
+    if (!options.orgId && !options.userId) {
+      return err({ code: "LIST_FILES_INVALID_OPTIONS", message: "Either orgId or userId is required for listing files" });
+    }
+    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.from(bucketName).list(searchPath, {
+      limit: options.limit || 100,
+      offset: options.offset || 0,
+      sortBy: { column: "created_at", order: "desc" }
+    });
+    if (error) {
+      log2.error("Failed to list files:", error);
+      return err({ code: "LIST_FILES_FAILED", message: error.message });
+    }
+    const files = (data || []).map((item) => ({
+      name: item.name,
+      path: `${searchPath}${item.name}`,
+      size: item.metadata?.size || 0,
+      mimeType: item.metadata?.mimetype || "application/octet-stream",
+      lastModified: item.updated_at || item.created_at || (/* @__PURE__ */ new Date()).toISOString(),
+      metadata: {
+        mimeType: item.metadata?.mimetype || "application/octet-stream",
+        size: item.metadata?.size || 0,
+        ...options.orgId && { orgId: options.orgId },
+        ...options.userId && { userId: options.userId },
+        appName: options.appName,
+        uploadedBy: "unknown",
+        uploadedAt: item.created_at || (/* @__PURE__ */ new Date()).toISOString(),
+        isPublic: options.isPublic || false
+      }
+    }));
+    return ok({
+      files,
+      totalCount: files.length,
+      hasMore: files.length >= (options.limit || 100)
+    });
+  } catch (error) {
+    log2.error("Failed to list files:", error);
+    return err({
+      code: "LIST_FILES_FAILED",
+      message: error instanceof Error ? error.message : "Unknown error"
+    });
+  }
+}
+async function downloadFile(supabase, path, isPublic = false) {
+  try {
+    const bucketName = getBucketName(isPublic);
+    const { data, error } = await supabase.storage.from(bucketName).download(path);
+    if (error) {
+      log2.error("Failed to download file:", error);
+      return err({ code: "DOWNLOAD_FAILED", message: error.message });
+    }
+    if (!data) {
+      return err({ code: "DOWNLOAD_FAILED", message: "No data returned" });
+    }
+    const fileName = path.split("/").pop() || "download";
+    const { data: fileInfo } = await supabase.storage.from(bucketName).list(path.split("/").slice(0, -1).join("/"), { search: fileName });
+    const metadata = fileInfo?.[0]?.metadata || {};
+    return ok({
+      blob: data,
+      metadata: {
+        name: fileName,
+        size: metadata.size || data.size,
+        type: metadata.mimetype || "application/octet-stream"
+      }
+    });
+  } catch (error) {
+    log2.error("Failed to download file:", error);
+    return err({
+      code: "DOWNLOAD_FAILED",
+      message: error instanceof Error ? error.message : "Unknown error"
+    });
+  }
+}
+async function archiveFile(supabase, path, options) {
+  try {
+    const bucketName = getBucketName(options.isPublic || false);
+    let archivedPath;
+    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 {
+      return err({ code: "ARCHIVE_FAILED", message: "Either orgId or userId is required for archiving files" });
+    }
+    const { error: copyError } = await supabase.storage.from(bucketName).copy(path, archivedPath);
+    if (copyError) {
+      return err({ code: "ARCHIVE_FAILED", message: copyError.message });
+    }
+    const deleteResult = await deleteFile(supabase, path, options.isPublic || false);
+    if (!deleteResult.ok) {
+      return err(deleteResult.error);
+    }
+    return ok(void 0);
+  } catch (error) {
+    return err({
+      code: "ARCHIVE_FAILED",
+      message: error instanceof Error ? error.message : "Unknown error"
+    });
+  }
+}
+var publicFileCache = /* @__PURE__ */ new Map();
+function usePublicFileDisplay(table_name, record_id, organisation_id, category, options) {
+  const {
+    cacheTtl = 30 * 60 * 1e3,
+    // 30 minutes
+    enableCache = true,
+    supabase
+  } = options;
+  const [fileUrl, setFileUrl] = useState(null);
+  const [fileReference, setFileReference] = useState(null);
+  const [fileReferences, setFileReferences] = useState([]);
+  const [fileUrls, setFileUrls] = useState(/* @__PURE__ */ new Map());
+  const [fileCount, setFileCount] = useState(0);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const fetchFiles = useCallback(async () => {
+    const emptySetters = () => {
+      applyEmptyPublicFileState(
+        setFileUrl,
+        setFileReference,
+        setFileReferences,
+        setFileUrls,
+        setFileCount,
+        setIsLoading,
+        setError
+      );
+    };
+    if (!table_name || !record_id || !supabase) {
+      emptySetters();
+      return;
+    }
+    warnInvalidOrganisationIdUuid(organisation_id ?? void 0);
+    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 : /* @__PURE__ */ new Map());
+        setFileReference(null);
+        setFileUrl(null);
+      }
+      setCachedPublicFileData(
+        cacheKey,
+        buildCacheDataFromRefs(fileRefs, category, supabase),
+        enableCache,
+        cacheTtl
+      );
+    } catch (err2) {
+      logger.error("usePublicFileDisplay", "Error fetching files", {
+        table_name,
+        record_id,
+        organisation_id,
+        category,
+        error: err2 instanceof Error ? err2.message : "Unknown error",
+        errorDetails: err2 instanceof Error ? err2.stack : String(err2)
+      });
+      const error2 = err2 instanceof Error ? err2 : new Error("Unknown error occurred");
+      setError(error2);
+      setFileUrl(null);
+      setFileReference(null);
+      setFileReferences([]);
+      setFileUrls(/* @__PURE__ */ new Map());
+      setFileCount(0);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [table_name, record_id, organisation_id, category, supabase, cacheTtl, enableCache]);
+  useEffect(() => {
+    if (table_name && record_id) {
+      fetchFiles();
+    } else {
+      setFileUrl(null);
+      setFileReference(null);
+      setFileReferences([]);
+      setFileUrls(/* @__PURE__ */ new Map());
+      setFileCount(0);
+      setIsLoading(false);
+      setError(null);
+    }
+  }, [fetchFiles, table_name, record_id, organisation_id]);
+  const refetch = useCallback(async () => {
+    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
+  };
+}
+function buildPublicFileCacheKey(table_name, record_id, organisation_id, category) {
+  return `public_file_${table_name}_${record_id}_${organisation_id === void 0 ? "undefined" : organisation_id ?? "null"}_${category || "all"}`;
+}
+function getCachedPublicFileData(cacheKey, enableCache) {
+  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, data, enableCache, cacheTtl) {
+  if (!enableCache) return;
+  publicFileCache.set(cacheKey, {
+    data,
+    timestamp: Date.now(),
+    ttl: cacheTtl
+  });
+}
+function mapRpcItemToRow(item, table_name, record_id, organisation_id) {
+  const metadata = item.file_metadata;
+  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 || (/* @__PURE__ */ new Date()).toISOString(),
+    updated_at: item.created_at || (/* @__PURE__ */ new Date()).toISOString(),
+    created_by: null
+  };
+}
+async function fetchPublicFileRowsWhenOrgUndefined(supabase, table_name, record_id, category) {
+  let userScopedFiles = [];
+  const orgScopedFiles = [];
+  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: void 0
+    });
+    if (!userRpcError && userData) {
+      userScopedFiles = userData.filter((item) => item.is_public === true && item.id && item.file_path && item.file_metadata).map((item) => 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: void 0
+    });
+    if (!userRpcError && userData) {
+      const ids = userData.map((item) => 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 || [];
+      }
+    }
+  }
+  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, table_name, record_id, organisation_id, category) {
+  if (category) {
+    const rpcParams = {
+      p_table_name: table_name,
+      p_record_id: record_id,
+      p_category: category,
+      p_organisation_id: organisation_id ?? void 0
+    };
+    const { data, error: rpcError2 } = await supabase.rpc("data_file_reference_by_category_list", rpcParams);
+    if (rpcError2) {
+      logger.error("usePublicFileDisplay", "RPC function error", {
+        function: "data_file_reference_by_category_list",
+        table_name,
+        record_id,
+        category,
+        organisation_id,
+        error: rpcError2.message,
+        errorCode: rpcError2.code,
+        errorDetails: rpcError2.details,
+        errorHint: rpcError2.hint
+      });
+      throw new Error(rpcError2.message || "Failed to fetch file reference");
+    }
+    if (!data || data.length === 0) return [];
+    return data.filter((item) => item.is_public === true && item.id && item.file_path && item.file_metadata).map((item) => 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 ?? void 0
+  });
+  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) => 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 || [];
+}
+async function fetchPublicFileRows(supabase, table_name, record_id, organisation_id, category) {
+  if (organisation_id === void 0) {
+    return fetchPublicFileRowsWhenOrgUndefined(supabase, table_name, record_id, category);
+  }
+  return fetchPublicFileRowsWhenOrgDefined(supabase, table_name, record_id, organisation_id, category);
+}
+function mapDbRowsToFileReferences(rows) {
+  return rows.map((f) => {
+    const fileName = f.file_path.split("/").pop() || "unknown";
+    const fileType = fileName.split(".").pop() || "unknown";
+    const metadata = f.file_metadata;
+    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 || "general_documents" /* GENERAL_DOCUMENTS */,
+        ...metadata || {}
+      },
+      organisation_id: f.organisation_id,
+      app_id: f.app_id,
+      is_public: f.is_public ?? true,
+      created_at: f.created_at || (/* @__PURE__ */ new Date()).toISOString(),
+      updated_at: f.updated_at || (/* @__PURE__ */ new Date()).toISOString()
+    };
+  });
+}
+function buildCacheDataFromRefs(fileRefs, category, supabase) {
+  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;
+  if (category) {
+    fileUrls = /* @__PURE__ */ new Map();
+  } else {
+    fileUrls = /* @__PURE__ */ new Map();
+    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
+  };
+}
+var emptyCacheData = {
+  fileUrl: null,
+  fileReference: null,
+  fileReferences: [],
+  fileUrls: /* @__PURE__ */ new Map(),
+  fileCount: 0
+};
+function applyEmptyPublicFileState(setFileUrl, setFileReference, setFileReferences, setFileUrls, setFileCount, setIsLoading, setError) {
+  setFileUrl(null);
+  setFileReference(null);
+  setFileReferences([]);
+  setFileUrls(/* @__PURE__ */ new Map());
+  setFileCount(0);
+  setIsLoading(false);
+  setError(null);
+}
+function applyCachedPublicFileState(cachedData, setFileUrl, setFileReference, setFileReferences, setFileUrls, setFileCount, setIsLoading, setError) {
+  setFileUrl(cachedData.fileUrl || null);
+  setFileReference(cachedData.fileReference || null);
+  setFileReferences(cachedData.fileReferences || []);
+  setFileUrls(cachedData.fileUrls || /* @__PURE__ */ new Map());
+  setFileCount(cachedData.fileCount || 0);
+  setIsLoading(false);
+  setError(null);
+}
+function warnInvalidOrganisationIdUuid(organisation_id) {
+  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 });
+  }
+}
+function clearPublicFileDisplayCache() {
+  for (const [key] of publicFileCache) {
+    if (key.startsWith("public_file_")) {
+      publicFileCache.delete(key);
+    }
+  }
+}
+function getPublicFileDisplayCacheStats() {
+  const keys = Array.from(publicFileCache.keys()).filter((key) => key.startsWith("public_file_"));
+  return {
+    size: keys.length,
+    keys
+  };
+}
+
+// src/utils/file-reference/index.ts
+var log3 = createLogger("FileReferenceService");
+function toApiError(error) {
+  const message = error instanceof Error ? error.message : "Unknown error";
+  const code = error instanceof Error && error.code ? error.code : "FILE_REFERENCE_ERROR";
+  return { code, message };
+}
+function mapFileReferenceRowToFileReference(f) {
+  const fileName = f.file_path.split("/").pop() || "unknown";
+  const fileType = fileName.split(".").pop() || "unknown";
+  const metadata = f.file_metadata;
+  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 || "general_documents" /* GENERAL_DOCUMENTS */,
+      ...metadata || {}
+    },
+    organisation_id: f.organisation_id,
+    app_id: f.app_id,
+    is_public: f.is_public ?? false,
+    created_at: f.created_at || (/* @__PURE__ */ new Date()).toISOString(),
+    updated_at: f.updated_at || (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+var FileReferenceServiceImpl = class {
+  constructor(supabase) {
+    this.supabase = supabase;
+  }
+  /**
+   * Helper method to get app name from app ID
+   */
+  async getAppName(appId) {
+    try {
+      const { data, error } = await this.supabase.from("rbac_apps").select("name").eq("id", appId).single();
+      if (error || !data) {
+        return "unknown";
+      }
+      return data.name || "unknown";
+    } catch {
+      return "unknown";
+    }
+  }
+  validateCreateOptions(options) {
+    const isUserScoped = !options.organisation_id && !!options.userId;
+    if (!isUserScoped && !options.organisation_id) {
+      return err({ code: "VALIDATION_ERROR", message: "organisation_id is required for file upload, or userId must be provided for user-scoped files" });
+    }
+    if (!options.table_name) {
+      return err({ code: "VALIDATION_ERROR", message: "table_name is required for file upload" });
+    }
+    if (!options.record_id) {
+      return err({ code: "VALIDATION_ERROR", message: "record_id is required for file upload" });
+    }
+    if (!options.folder) {
+      return err({ code: "VALIDATION_ERROR", message: "folder is required for file upload. The folder prop determines the storage path." });
+    }
+    return ok({ isUserScoped });
+  }
+  async resolveAuthenticatedUserIdForUserScoped() {
+    const { data: { user: authUser }, error: authError } = await this.supabase.auth.getUser();
+    if (authError || !authUser) {
+      return err({ code: "UNAUTHORIZED", message: "User must be authenticated to upload user-scoped files" });
+    }
+    log3.debug("Using authenticated user ID for user-scoped file upload", { userId: authUser.id });
+    return ok(authUser.id);
+  }
+  async checkSuperAdminUser(userId) {
+    if (!userId) return false;
+    try {
+      const { isSuperAdmin } = await import('./api-BZR2CYXL.js');
+      const superResult = await isSuperAdmin(userId);
+      if (superResult.ok && superResult.data) {
+        log3.debug("Super admin detected - bypassing permission checks", { userId });
+        return true;
+      }
+      return false;
+    } catch (superAdminCheckError) {
+      log3.warn("Failed to check super-admin status, proceeding with normal permission checks", superAdminCheckError);
+      return false;
+    }
+  }
+  async uploadFileAndExtractMetadata(options, file, authenticatedUserId, isUserScoped) {
+    const userId = authenticatedUserId || (isUserScoped ? void 0 : options.userId);
+    const uploadResult = await uploadFile(this.supabase, file, {
+      appName: "file-reference",
+      orgId: options.organisation_id || void 0,
+      userId,
+      isPublic: options.is_public || false,
+      customPath: options.folder
+    });
+    if (!uploadResult.ok) return err(uploadResult.error);
+    const metadataResult = await extractFileMetadata(file, {
+      appName: "file-reference",
+      orgId: options.organisation_id || void 0,
+      userId,
+      isPublic: options.is_public || false
+    }, "system");
+    if (!metadataResult.ok) return err(metadataResult.error);
+    return ok({ path: uploadResult.data.path, metadata: metadataResult.data });
+  }
+  async setOrgContextIfNeeded(isUserScoped, organisation_id) {
+    if (isUserScoped || !organisation_id) return;
+    const ctxResult = await setOrganisationContext(this.supabase, organisation_id);
+    if (!ctxResult.ok) {
+      log3.warn("setOrganisationContext failed (non-fatal):", ctxResult.error.message);
+    }
+  }
+  async resolveRpcUserId(authenticatedUserId, options) {
+    if (authenticatedUserId) return authenticatedUserId;
+    if (options.userId) return options.userId;
+    const { data: { user: authUser } } = await this.supabase.auth.getUser();
+    return authUser?.id ?? null;
+  }
+  async buildPermissionDeniedMessage(options, isSuperAdminUser) {
+    const appName = await this.getAppName(options.app_id).catch(() => "unknown");
+    const pageContextDisplay = options.pageContext || "undefined";
+    return isSuperAdminUser ? `File upload failed for super-admin user. Page context: '${pageContextDisplay}', App: '${appName}'.` : `File upload denied: insufficient permissions. You need 'create:page.${pageContextDisplay}' or 'update:page.${pageContextDisplay}' for the '${pageContextDisplay}' page.`;
+  }
+  async rollbackUploadAndErr(filePath, isPublic, code, message) {
+    await deleteFile(this.supabase, filePath, isPublic);
+    return err({ code, message });
+  }
+  async fetchCreatedFileReference(createdId) {
+    const { data: fileRef, error: fetchError } = await this.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").eq("id", createdId).single();
+    if (fetchError || !fileRef) {
+      return err({ code: "FETCH_FAILED", message: fetchError?.message ?? "Failed to fetch created file reference" });
+    }
+    return ok(fileRef);
+  }
+  buildCreateRpcPayload(options, filePath, file, metadata, rpcUserId) {
+    return {
+      p_table_name: options.table_name,
+      p_record_id: options.record_id,
+      p_file_path: filePath,
+      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,
+      p_file_metadata: {
+        fileName: file.name,
+        fileType: file.type,
+        fileSize: file.size,
+        category: options.category,
+        ...metadata,
+        ...options.custom_metadata
+      },
+      p_is_public: options.is_public || false,
+      p_user_id: rpcUserId
+    };
+  }
+  /**
+   * Creates a file reference by uploading a file to storage and linking it in the database.
+   * 
+   * Storage Flow:
+   * 1. Upload file to storage bucket first (files or public-files based on is_public flag)
+   *    - Path format: {orgId}/{folder}/{timestamp-uuid-filename}
+   *    - Bucket selection: 'files' (private) or 'public-files' (public)
+   * 2. Extract file metadata (dimensions, hash, etc.)
+   * 3. Set organisation context for RLS policies
+   * 4. Create database reference via RPC function
+   * 5. If DB insert fails, rollback by deleting uploaded file
+   * 
+   * This ensures atomicity: either both storage and DB succeed, or both are cleaned up.
+   */
+  async createFileReference(options, file) {
+    try {
+      const validation = this.validateCreateOptions(options);
+      if (!validation.ok) return validation;
+      const { isUserScoped } = validation.data;
+      let authenticatedUserId;
+      if (isUserScoped) {
+        const authResult = await this.resolveAuthenticatedUserIdForUserScoped();
+        if (!authResult.ok) return authResult;
+        authenticatedUserId = authResult.data;
+      }
+      const isSuperAdminUser = await this.checkSuperAdminUser(authenticatedUserId || options.userId);
+      const uploadResult = await this.uploadFileAndExtractMetadata(options, file, authenticatedUserId, isUserScoped);
+      if (!uploadResult.ok) return uploadResult;
+      const { path: filePath, metadata } = uploadResult.data;
+      await this.setOrgContextIfNeeded(isUserScoped, options.organisation_id ?? void 0);
+      const rpcUserId = await this.resolveRpcUserId(authenticatedUserId, options);
+      const payload = this.buildCreateRpcPayload(options, filePath, file, metadata, rpcUserId);
+      const { data, error } = await this.supabase.rpc("data_file_reference_create", payload);
+      if (error) {
+        return await this.rollbackUploadAndErr(filePath, options.is_public ?? false, "CREATE_FAILED", error.message);
+      }
+      if (!data || data === null) {
+        const message = await this.buildPermissionDeniedMessage(options, isSuperAdminUser);
+        return await this.rollbackUploadAndErr(filePath, options.is_public ?? false, "PERMISSION_DENIED", message);
+      }
+      const fetchResult = await this.fetchCreatedFileReference(data);
+      if (!fetchResult.ok) {
+        return await this.rollbackUploadAndErr(
+          filePath,
+          options.is_public ?? false,
+          "FETCH_FAILED",
+          fetchResult.error.message
+        );
+      }
+      invalidateFileDisplayCache(
+        options.table_name,
+        options.record_id,
+        options.organisation_id || null,
+        options.category
+      );
+      return ok(fetchResult.data);
+    } catch (error) {
+      log3.error("Error creating file reference:", error);
+      return err(toApiError(error));
+    }
+  }
+  async getFileReference(table_name, record_id, organisation_id) {
+    try {
+      let query = this.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").eq("table_name", table_name).eq("record_id", record_id);
+      if (organisation_id === null || organisation_id === void 0) {
+        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") {
+          return ok(null);
+        }
+        return err({ code: "FETCH_FAILED", message: error.message });
+      }
+      return ok(data);
+    } catch (error) {
+      log3.error("Error getting file reference:", error);
+      return err(toApiError(error));
+    }
+  }
+  async getFileUrl(table_name, record_id, organisation_id) {
+    try {
+      const refResult = await this.getFileReference(table_name, record_id, organisation_id);
+      if (!refResult.ok) {
+        return refResult;
+      }
+      const fileRef = refResult.data;
+      if (!fileRef) {
+        return ok(null);
+      }
+      if (fileRef.is_public) {
+        const { data: pathData } = await this.supabase.rpc("data_file_reference_url_get", {
+          p_table_name: table_name,
+          p_record_id: record_id,
+          p_organisation_id: organisation_id
+        });
+        if (!pathData) {
+          return ok(null);
+        }
+        return ok(getPublicUrl(this.supabase, pathData, true));
+      }
+      return this.getSignedUrl(table_name, record_id, organisation_id);
+    } catch (error) {
+      log3.error("Error getting file URL:", error);
+      return err(toApiError(error));
+    }
+  }
+  async getSignedUrl(table_name, record_id, organisation_id, expires_in = 3600) {
+    try {
+      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 ?? null,
+        p_expires_in: expires_in
+      });
+      if (error) {
+        return err({ code: "SIGNED_URL_FAILED", message: error.message });
+      }
+      if (!filePath) {
+        return ok(null);
+      }
+      const signedUrlResult = await getSignedUrl(this.supabase, filePath, {
+        appName: "file-reference",
+        orgId: organisation_id,
+        userId: organisation_id ? void 0 : record_id,
+        expiresIn: expires_in
+      });
+      if (!signedUrlResult.ok) {
+        return err(signedUrlResult.error);
+      }
+      return ok(signedUrlResult.data.url ?? null);
+    } catch (error) {
+      log3.error("Error getting signed URL:", error);
+      return err(toApiError(error));
+    }
+  }
+  async updateFileReference(id, updates) {
+    try {
+      const { data, error } = await this.supabase.from("core_file_references").update(updates).eq("id", id).select().single();
+      if (error) {
+        return err({ code: "UPDATE_FAILED", message: error.message });
+      }
+      return ok(data);
+    } catch (error) {
+      log3.error("Error updating file reference:", error);
+      return err(toApiError(error));
+    }
+  }
+  async deleteFileReference(table_name, record_id, organisation_id, delete_file = false) {
+    try {
+      const refResult = await this.getFileReference(table_name, record_id, organisation_id);
+      const fileRef = refResult.ok ? refResult.data : null;
+      const { error } = await this.supabase.rpc("data_file_reference_delete", {
+        p_table_name: table_name,
+        p_record_id: record_id,
+        p_organisation_id: organisation_id ?? null,
+        p_delete_file: delete_file
+      });
+      if (error) {
+        return err({ code: "DELETE_FAILED", message: error.message });
+      }
+      if (delete_file && fileRef) {
+        await deleteFile(this.supabase, fileRef.file_path, fileRef.is_public || false);
+      }
+      return ok(true);
+    } catch (error) {
+      log3.error("Error deleting file reference:", error);
+      return err(toApiError(error));
+    }
+  }
+  async listFileReferences(table_name, record_id, organisation_id) {
+    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 ?? null
+      });
+      if (error) {
+        return err({ code: "LIST_FAILED", message: error.message });
+      }
+      if (!data || data.length === 0) {
+        return ok([]);
+      }
+      const fileReferences = data.filter((item) => item.id && item.file_path && item.file_metadata).map((item) => {
+        const fileName = item.file_path.split("/").pop() || "unknown";
+        const fileType = fileName.split(".").pop() || "unknown";
+        return {
+          id: item.id,
+          table_name,
+          record_id,
+          file_path: item.file_path,
+          file_metadata: { fileName, fileType, ...item.file_metadata || {} },
+          organisation_id: organisation_id ?? null,
+          app_id: item.file_metadata?.app_id ? assertAppId(item.file_metadata.app_id) : assertAppId(""),
+          is_public: item.is_public ?? false,
+          created_at: item.created_at || (/* @__PURE__ */ new Date()).toISOString(),
+          updated_at: item.created_at || (/* @__PURE__ */ new Date()).toISOString()
+        };
+      });
+      return ok(fileReferences);
+    } catch (error) {
+      log3.error("Error listing file references:", error);
+      return err(toApiError(error));
+    }
+  }
+  async getFileCount(table_name, record_id, organisation_id) {
+    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 ?? null
+      });
+      if (error) {
+        return err({ code: "COUNT_FAILED", message: error.message });
+      }
+      return ok(data ?? 0);
+    } catch (error) {
+      log3.error("Error getting file count:", error);
+      return err(toApiError(error));
+    }
+  }
+  async getFileReferenceById(id, organisation_id) {
+    try {
+      const { data, error } = await this.supabase.rpc("data_file_reference_get", {
+        p_file_reference_id: id,
+        p_organisation_id: organisation_id ?? null
+      });
+      if (error) {
+        return err({ code: "FETCH_FAILED", message: error.message });
+      }
+      if (!data || data.length === 0) {
+        return ok(null);
+      }
+      return ok(data[0]);
+    } catch (error) {
+      log3.error("Error getting file reference by ID:", error);
+      return err(toApiError(error));
+    }
+  }
+  async getFilesByCategory(table_name, record_id, category, organisation_id) {
+    try {
+      const { data, error } = await this.supabase.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 ?? null
+      });
+      if (error) {
+        log3.error("RPC ERROR getting files by category:", { error, table_name, record_id, category });
+        return err({ code: "LIST_FAILED", message: error.message });
+      }
+      if (!data || data.length === 0) {
+        return ok([]);
+      }
+      const fileReferences = data.filter((item) => {
+        const fileCategory = item.file_metadata?.category;
+        return fileCategory === category && item.id && item.file_path && item.file_metadata;
+      }).map((item) => ({
+        id: item.id,
+        table_name,
+        record_id,
+        file_path: item.file_path,
+        file_metadata: {
+          fileName: item.file_path.split("/").pop() || "unknown",
+          fileType: item.file_path.split(".").pop() || "unknown",
+          category: item.file_metadata?.category || "general_documents" /* GENERAL_DOCUMENTS */,
+          ...item.file_metadata || {}
+        },
+        organisation_id: organisation_id ?? null,
+        app_id: item.file_metadata?.app_id ? assertAppId(item.file_metadata.app_id) : assertAppId(""),
+        is_public: item.is_public ?? false,
+        created_at: item.created_at || (/* @__PURE__ */ new Date()).toISOString(),
+        updated_at: item.created_at || (/* @__PURE__ */ new Date()).toISOString()
+      }));
+      return ok(fileReferences);
+    } catch (error) {
+      log3.error("Error getting files by category:", error);
+      return err(toApiError(error));
+    }
+  }
+  async uploadMultipleFiles(options, files) {
+    const success = [];
+    const failed = [];
+    const results = [];
+    for (const file of files) {
+      const result = await this.createFileReference(options, file);
+      if (result.ok) {
+        const fileReference = result.data;
+        success.push(fileReference);
+        results.push({
+          file,
+          result: {
+            file_reference: fileReference,
+            file_url: fileReference.is_public ? getPublicUrl(this.supabase, fileReference.file_path, true) : ""
+          }
+        });
+      } else {
+        failed.push({ file, error: result.error.message });
+        results.push({ file, result: null, error: result.error.message });
+      }
+    }
+    return ok({
+      success,
+      failed,
+      total: results.length,
+      successful: success.length,
+      results
+    });
+  }
+};
+function createFileReferenceService(supabase) {
+  return new FileReferenceServiceImpl(supabase);
+}
+async function uploadFileWithReference(supabase, options, file) {
+  const service = createFileReferenceService(supabase);
+  const result = await service.createFileReference(options, file);
+  if (!result.ok) {
+    return result;
+  }
+  const fileReference = result.data;
+  let urlString;
+  if (options.is_public) {
+    urlString = getPublicUrl(supabase, fileReference.file_path, true);
+  } else {
+    const signedResult = await getSignedUrl(supabase, fileReference.file_path, {
+      appName: "file-reference",
+      orgId: options.organisation_id || void 0,
+      userId: options.userId || void 0,
+      expiresIn: 3600
+    });
+    urlString = signedResult.ok ? signedResult.data.url ?? "" : "";
+  }
+  return ok({
+    file_reference: fileReference,
+    file_url: urlString,
+    signed_url: options.is_public ? void 0 : urlString || void 0
+  });
+}
+
+// src/components/FileDisplay/useFileDisplayData.ts
+async function fetchFileDisplayDataInternal(params) {
+  const { table_name, record_id, organisation_id, category, supabase } = params;
+  if (!supabase) {
+    return [];
+  }
+  let query = 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").eq("table_name", table_name).eq("record_id", record_id);
+  if (organisation_id === void 0 || organisation_id === null) {
+    query = query.is("organisation_id", null);
+  } else {
+    query = query.eq("organisation_id", organisation_id);
+  }
+  if (category !== void 0 && category !== null) {
+    query = query.contains("file_metadata", { category });
+  }
+  const { data, error } = await query.order("created_at", { ascending: false });
+  if (error) {
+    throw new Error(error.message ?? "Failed to fetch file references");
+  }
+  const rows = data ?? [];
+  return rows.map(mapFileReferenceRowToFileReference);
+}
+
+// src/components/FileDisplay/useFileDisplay.ts
+var authenticatedFileCache = /* @__PURE__ */ new Map();
+var MAX_CACHE_SIZE2 = 100;
+function cleanupCache() {
+  const now = Date.now();
+  const entries = Array.from(authenticatedFileCache.entries());
+  const expiredKeys = [];
+  entries.forEach(([key, value]) => {
+    if (now - value.timestamp >= value.ttl) {
+      expiredKeys.push(key);
+    }
+  });
+  expiredKeys.forEach((key) => authenticatedFileCache.delete(key));
+  if (authenticatedFileCache.size > MAX_CACHE_SIZE2) {
+    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_SIZE2);
+    toRemove.forEach(([key]) => authenticatedFileCache.delete(key));
+  }
+}
+function getFileDisplayCacheKey(table_name, record_id, organisation_id, category) {
+  return `file_${table_name}_${record_id}_${organisation_id === void 0 ? "undefined" : organisation_id ?? "null"}_${category || "all"}`;
+}
+async function tryApplyCacheHit(cacheKey, enableCache, cacheTtl, supabase, organisation_id, record_id, safeSetState, setters) {
+  if (!enableCache || !supabase) return false;
+  const cached = authenticatedFileCache.get(cacheKey);
+  if (!cached || Date.now() - cached.timestamp >= cached.ttl) return false;
+  const cachedData = cached.data;
+  if (cachedData.fileReference && !cachedData.fileUrl && cachedData.fileReference.is_public === false && supabase) {
+    try {
+      const signedUrlResult = await getSignedUrl(supabase, cachedData.fileReference.file_path, {
+        appName: "pace-core",
+        orgId: organisation_id,
+        userId: organisation_id ? void 0 : record_id,
+        expiresIn: 3600
+      });
+      const regeneratedUrl = signedUrlResult.ok ? signedUrlResult.data.url : null;
+      safeSetState(setters.setFileUrl, regeneratedUrl);
+      safeSetState(setters.setFileReference, cachedData.fileReference);
+      safeSetState(setters.setFileReferences, cachedData.fileReferences || []);
+      safeSetState(setters.setFileUrls, cachedData.fileUrls || /* @__PURE__ */ new Map());
+      safeSetState(setters.setFileCount, cachedData.fileCount || 0);
+      safeSetState(setters.setIsLoading, false);
+      safeSetState(setters.setError, null);
+      return true;
+    } catch (err2) {
+      logger.warn("useFileDisplay", "Failed to regenerate signed URL from cache, falling back to fetch:", err2);
+    }
+  }
+  safeSetState(setters.setFileUrl, cachedData.fileUrl || null);
+  safeSetState(setters.setFileReference, cachedData.fileReference || null);
+  safeSetState(setters.setFileReferences, cachedData.fileReferences || []);
+  safeSetState(setters.setFileUrls, cachedData.fileUrls || /* @__PURE__ */ new Map());
+  safeSetState(setters.setFileCount, cachedData.fileCount || 0);
+  safeSetState(setters.setIsLoading, false);
+  safeSetState(setters.setError, null);
+  return true;
+}
+async function applyFetchedFilesAndCache(files, category, table_name, record_id, organisation_id, supabase, cacheKey, enableCache, cacheTtl, safeSetState, setters) {
+  safeSetState(setters.setFileReferences, files);
+  safeSetState(setters.setFileCount, files.length);
+  if (category && files.length > 0) {
+    const firstFile = files[0];
+    safeSetState(setters.setFileReference, firstFile);
+    let url = 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,
+        userId: organisation_id ? void 0 : record_id,
+        expiresIn: 3600
+      });
+      url = signedUrlResult.ok ? signedUrlResult.data.url : null;
+      if (!url) {
+        logger.warn("useFileDisplay", "Failed to generate signed URL for file:", {
+          file_path: firstFile.file_path,
+          record_id,
+          table_name
+        });
+      }
+    }
+    safeSetState(setters.setFileUrl, url);
+  } else {
+    const urlResult = await generateFileUrlsBatch(supabase, files, {
+      appName: "pace-core",
+      orgId: organisation_id,
+      userId: organisation_id ? void 0 : record_id,
+      expiresIn: 3600
+    });
+    const urlMap = urlResult.ok ? urlResult.data : /* @__PURE__ */ new Map();
+    safeSetState(setters.setFileUrls, urlMap);
+    safeSetState(setters.setFileReference, null);
+    safeSetState(setters.setFileUrl, null);
+  }
+  if (enableCache) {
+    const cacheData = {
+      fileUrl: null,
+      fileReference: category && files.length > 0 ? files[0] : null,
+      fileReferences: files,
+      fileUrls: /* @__PURE__ */ new Map(),
+      fileCount: files.length
+    };
+    if (category && files.length > 0) {
+      const firstFile = files[0];
+      cacheData.fileUrl = firstFile.is_public ? getPublicUrl(supabase, firstFile.file_path, true) : null;
+    } else {
+      const urlMap = /* @__PURE__ */ new Map();
+      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();
+  }
+}
+function useFileDisplay(table_name, record_id, organisation_id, category, options) {
+  const {
+    cacheTtl = 30 * 60 * 1e3,
+    // 30 minutes
+    enableCache = true,
+    supabase
+  } = options;
+  const [fileUrl, setFileUrl] = useState(null);
+  const [fileReference, setFileReference] = useState(null);
+  const [fileReferences, setFileReferences] = useState([]);
+  const [fileUrls, setFileUrls] = useState(/* @__PURE__ */ new Map());
+  const [fileCount, setFileCount] = useState(0);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const isMountedRef = useRef(true);
+  const safeSetState = (setter, value) => {
+    if (isMountedRef.current) {
+      setter(value);
+    }
+  };
+  const fetchFiles = useCallback(async () => {
+    if (!table_name || !record_id || !supabase) {
+      safeSetState(setFileUrl, null);
+      safeSetState(setFileReference, null);
+      safeSetState(setFileReferences, []);
+      safeSetState(setFileUrls, /* @__PURE__ */ new Map());
+      safeSetState(setFileCount, 0);
+      safeSetState(setIsLoading, false);
+      return;
+    }
+    if (organisation_id) {
+      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("useFileDisplay", "Invalid organisationId format (not a valid UUID):", organisation_id);
+      }
+    }
+    safeSetState(setIsLoading, true);
+    safeSetState(setError, null);
+    const cacheKey = getFileDisplayCacheKey(table_name, record_id, organisation_id, category);
+    const applied = await tryApplyCacheHit(
+      cacheKey,
+      enableCache,
+      cacheTtl,
+      supabase,
+      organisation_id,
+      record_id,
+      safeSetState,
+      {
+        setFileUrl,
+        setFileReference,
+        setFileReferences,
+        setFileUrls,
+        setFileCount,
+        setIsLoading,
+        setError
+      }
+    );
+    if (applied) return;
+    try {
+      const files = await fetchFileDisplayDataInternal({
+        table_name,
+        record_id,
+        organisation_id,
+        category,
+        supabase
+      });
+      if (files.length === 0) {
+        safeSetState(setFileUrl, null);
+        safeSetState(setFileReference, null);
+        safeSetState(setFileReferences, []);
+        safeSetState(setFileUrls, /* @__PURE__ */ new Map());
+        safeSetState(setFileCount, 0);
+        if (enableCache) {
+          authenticatedFileCache.set(cacheKey, {
+            data: { fileUrl: null, fileReference: null, fileReferences: [], fileUrls: /* @__PURE__ */ new Map(), fileCount: 0 },
+            timestamp: Date.now(),
+            ttl: cacheTtl
+          });
+          cleanupCache();
+        }
+        return;
+      }
+      await applyFetchedFilesAndCache(
+        files,
+        category,
+        table_name,
+        record_id,
+        organisation_id,
+        supabase,
+        cacheKey,
+        enableCache,
+        cacheTtl,
+        safeSetState,
+        { setFileUrl, setFileReference, setFileReferences, setFileUrls, setFileCount }
+      );
+    } catch (err2) {
+      logger.error("useFileDisplay", "Error fetching files:", err2);
+      const error2 = err2 instanceof Error ? err2 : new Error("Unknown error occurred");
+      safeSetState(setError, error2);
+      safeSetState(setFileUrl, null);
+      safeSetState(setFileReference, null);
+      safeSetState(setFileReferences, []);
+      safeSetState(setFileUrls, /* @__PURE__ */ new Map());
+      safeSetState(setFileCount, 0);
+    } finally {
+      safeSetState(setIsLoading, false);
+    }
+  }, [table_name, record_id, organisation_id, category, supabase, cacheTtl, enableCache]);
+  useEffect(() => {
+    isMountedRef.current = true;
+    if (table_name && record_id && supabase) {
+      fetchFiles().catch((err2) => {
+        if (isMountedRef.current) {
+          safeSetState(setError, err2 instanceof Error ? err2 : new Error("Unknown error"));
+        }
+      });
+    } else {
+      safeSetState(setFileUrl, null);
+      safeSetState(setFileReference, null);
+      safeSetState(setFileReferences, []);
+      safeSetState(setFileUrls, /* @__PURE__ */ new Map());
+      safeSetState(setFileCount, 0);
+      safeSetState(setIsLoading, false);
+      safeSetState(setError, null);
+    }
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, [table_name, record_id, organisation_id, supabase]);
+  const refetch = useCallback(async () => {
+    if (!table_name || !record_id || !supabase) return;
+    if (enableCache) {
+      authenticatedFileCache.delete(getFileDisplayCacheKey(table_name, record_id, organisation_id, category));
+    }
+    await fetchFiles();
+  }, [fetchFiles, table_name, record_id, organisation_id, category, supabase, enableCache]);
+  return {
+    fileUrl,
+    fileReference,
+    fileReferences,
+    fileUrls,
+    fileCount,
+    isLoading,
+    error,
+    refetch
+  };
+}
+function clearFileDisplayCache() {
+  for (const [key] of authenticatedFileCache) {
+    if (key.startsWith("file_")) {
+      authenticatedFileCache.delete(key);
+    }
+  }
+}
+function getFileDisplayCacheStats() {
+  const keys = Array.from(authenticatedFileCache.keys()).filter((key) => key.startsWith("file_"));
+  return {
+    size: keys.length,
+    keys
+  };
+}
+function invalidateFileDisplayCache(table_name, record_id, organisation_id, category) {
+  const orgId = organisation_id ?? void 0;
+  authenticatedFileCache.delete(getFileDisplayCacheKey(table_name, record_id, orgId, category));
+  if (category) {
+    authenticatedFileCache.delete(getFileDisplayCacheKey(table_name, record_id, orgId, void 0));
+  }
+}
+var log4 = createLogger("useEventTheme");
+function useEventTheme(event) {
+  const location = useLocation();
+  const eventServiceContext = useContext(EventServiceContext);
+  const eventService = eventServiceContext?.eventService ?? null;
+  useEffect(() => {
+    if (event !== void 0 || !eventService) return;
+    const applyThemeFromService = () => {
+      const isOnLoginRoute = location.pathname === "/login" || location.pathname.startsWith("/login/");
+      if (isOnLoginRoute) {
+        clearPalette();
+        return;
+      }
+      const current = eventService.getSelectedEvent();
+      if (!current?.event_colours) {
+        clearPalette();
+        return;
+      }
+      const normalized = parseAndNormalizeEventColours(current.event_colours);
+      if (normalized) {
+        try {
+          applyPalette(normalized, current.event_name ?? "");
+        } catch (err2) {
+          log4.error("Failed to apply event palette (subscription):", err2);
+        }
+      } else {
+        clearPalette();
+      }
+    };
+    applyThemeFromService();
+    const unsubscribe = eventService.subscribe(applyThemeFromService);
+    return () => {
+      unsubscribe();
+    };
+  }, [event, eventService, location.pathname]);
+  const eventsContextSelectedEvent = eventService?.getSelectedEvent() ?? null;
+  const selectedEvent = event !== void 0 ? event : eventsContextSelectedEvent;
+  useEffect(() => {
+    const isOnLoginRoute = location.pathname === "/login" || location.pathname.startsWith("/login");
+    if (isOnLoginRoute) {
+      clearPalette();
+      return;
+    }
+    if (event === void 0) {
+      return;
+    }
+    if (!selectedEvent) {
+      clearPalette();
+      return;
+    }
+    const eventColours = selectedEvent.event_colours;
+    const normalized = parseAndNormalizeEventColours(eventColours);
+    if (!normalized) {
+      clearPalette();
+      return;
+    }
+    try {
+      applyPalette(normalized, selectedEvent.event_name ?? "");
+    } catch (error) {
+      log4.error("Failed to apply event palette:", error);
+    }
+  }, [selectedEvent, location.pathname, event]);
+}
+function usePreventTabReload(options = {}) {
+  const { enabled = true, gracePeriodMs = 2e3 } = options;
+  const isRestoringFromCacheRef = useRef(false);
+  const gracePeriodTimeoutRef = useRef(null);
+  useEffect(() => {
+    if (!enabled || typeof window === "undefined") return;
+    const handlePageShow = (event) => {
+      if (event.persisted) {
+        isRestoringFromCacheRef.current = true;
+        if (gracePeriodTimeoutRef.current) {
+          clearTimeout(gracePeriodTimeoutRef.current);
+        }
+        gracePeriodTimeoutRef.current = setTimeout(() => {
+          isRestoringFromCacheRef.current = false;
+        }, gracePeriodMs);
+      }
+    };
+    const handleVisibilityChange = () => {
+      if (!document.hidden) {
+        isRestoringFromCacheRef.current = true;
+        if (gracePeriodTimeoutRef.current) {
+          clearTimeout(gracePeriodTimeoutRef.current);
+        }
+        gracePeriodTimeoutRef.current = setTimeout(() => {
+          isRestoringFromCacheRef.current = false;
+        }, gracePeriodMs);
+      }
+    };
+    window.addEventListener("pageshow", handlePageShow);
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+    return () => {
+      window.removeEventListener("pageshow", handlePageShow);
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+      if (gracePeriodTimeoutRef.current) {
+        clearTimeout(gracePeriodTimeoutRef.current);
+      }
+    };
+  }, [enabled, gracePeriodMs]);
+}
+
+export { APP_PATH_MAPPING, DEFAULT_FILE_SIZE_LIMIT, FILE_SIZE_LIMITS, STORAGE_CONFIG, archiveFile, cleanupQueryCache, clearFileDisplayCache, clearPublicFileDisplayCache, createFileReferenceService, deleteFile, downloadFile, extractFileMetadata, generateFilePath, generateFileUrlsBatch, generateUniqueFileName, getBucketName, getFileDisplayCacheStats, getFileSizeLimit, getPublicFileDisplayCacheStats, getPublicUrl, getSignedUrl, invalidateFileDisplayCache, listFiles, queryCacheHelpers, uploadFile, uploadFileWithReference, useAddressAutocomplete, useDebounce, useEventTheme, useFileDisplay, usePreventTabReload, usePublicFileDisplay, useQueryCache, validateFileSize };