@jmruthers/pace-core 0.5.102 → 0.5.103

package/docs/api/interfaces/UseEventLogoOptions.md

@@ -1,74 +0,0 @@
-[@jmruthers/pace-core - v0.5.102](../README.md) / [Exports](../modules.md) / UseEventLogoOptions
-
-# Interface: UseEventLogoOptions
-
-## Table of contents
-
-### Properties
-
-- [cacheTtl](UseEventLogoOptions.md#cachettl)
-- [enableCache](UseEventLogoOptions.md#enablecache)
-- [validateImage](UseEventLogoOptions.md#validateimage)
-- [generateFallbackText](UseEventLogoOptions.md#generatefallbacktext)
-
-## Properties
-
-### cacheTtl
-
-• `Optional` **cacheTtl**: `number`
-
-Cache TTL in milliseconds (default: 30 minutes)
-
-#### Defined in
-
-[packages/core/src/hooks/useEventLogo.ts:67](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/useEventLogo.ts#L67)
-
-___
-
-### enableCache
-
-• `Optional` **enableCache**: `boolean`
-
-Whether to enable caching (default: true)
-
-#### Defined in
-
-[packages/core/src/hooks/useEventLogo.ts:69](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/useEventLogo.ts#L69)
-
-___
-
-### validateImage
-
-• `Optional` **validateImage**: `boolean`
-
-Whether to validate image existence (default: true)
-
-#### Defined in
-
-[packages/core/src/hooks/useEventLogo.ts:71](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/useEventLogo.ts#L71)
-
-___
-
-### generateFallbackText
-
-• `Optional` **generateFallbackText**: (`eventName`: `string`) => `string`
-
-Custom fallback text generator
-
-#### Type declaration
-
-▸ (`eventName`): `string`
-
-##### Parameters
-
-| Name | Type |
-| :------ | :------ |
-| `eventName` | `string` |
-
-##### Returns
-
-`string`
-
-#### Defined in
-
-[packages/core/src/hooks/useEventLogo.ts:73](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/useEventLogo.ts#L73)

package/docs/api/interfaces/UseEventLogoReturn.md

@@ -1,81 +0,0 @@
-[@jmruthers/pace-core - v0.5.102](../README.md) / [Exports](../modules.md) / UseEventLogoReturn
-
-# Interface: UseEventLogoReturn
-
-## Table of contents
-
-### Properties
-
-- [logoUrl](UseEventLogoReturn.md#logourl)
-- [fallbackText](UseEventLogoReturn.md#fallbacktext)
-- [isLoading](UseEventLogoReturn.md#isloading)
-- [error](UseEventLogoReturn.md#error)
-- [refetch](UseEventLogoReturn.md#refetch)
-
-## Properties
-
-### logoUrl
-
-• **logoUrl**: ``null`` \| `string`
-
-The logo URL if available, null if not found or error
-
-#### Defined in
-
-[packages/core/src/hooks/useEventLogo.ts:54](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/useEventLogo.ts#L54)
-
-___
-
-### fallbackText
-
-• **fallbackText**: `string`
-
-Fallback text (event initials) if no logo is available
-
-#### Defined in
-
-[packages/core/src/hooks/useEventLogo.ts:56](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/useEventLogo.ts#L56)
-
-___
-
-### isLoading
-
-• **isLoading**: `boolean`
-
-Whether the logo is currently loading
-
-#### Defined in
-
-[packages/core/src/hooks/useEventLogo.ts:58](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/useEventLogo.ts#L58)
-
-___
-
-### error
-
-• **error**: ``null`` \| `Error`
-
-Any error that occurred during loading
-
-#### Defined in
-
-[packages/core/src/hooks/useEventLogo.ts:60](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/useEventLogo.ts#L60)
-
-___
-
-### refetch
-
-• **refetch**: () => `Promise`\<`void`\>
-
-Function to manually refetch the logo
-
-#### Type declaration
-
-▸ (): `Promise`\<`void`\>
-
-##### Returns
-
-`Promise`\<`void`\>
-
-#### Defined in
-
-[packages/core/src/hooks/useEventLogo.ts:62](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/useEventLogo.ts#L62)

package/docs/api/interfaces/UsePublicEventLogoOptions.md

@@ -1,87 +0,0 @@
-[@jmruthers/pace-core - v0.5.102](../README.md) / [Exports](../modules.md) / UsePublicEventLogoOptions
-
-# Interface: UsePublicEventLogoOptions
-
-## Table of contents
-
-### Properties
-
-- [cacheTtl](UsePublicEventLogoOptions.md#cachettl)
-- [enableCache](UsePublicEventLogoOptions.md#enablecache)
-- [validateImage](UsePublicEventLogoOptions.md#validateimage)
-- [generateFallbackText](UsePublicEventLogoOptions.md#generatefallbacktext)
-- [supabase](UsePublicEventLogoOptions.md#supabase)
-
-## Properties
-
-### cacheTtl
-
-• `Optional` **cacheTtl**: `number`
-
-Cache TTL in milliseconds (default: 30 minutes)
-
-#### Defined in
-
-[packages/core/src/hooks/public/usePublicEventLogo.ts:91](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/public/usePublicEventLogo.ts#L91)
-
-___
-
-### enableCache
-
-• `Optional` **enableCache**: `boolean`
-
-Whether to enable caching (default: true)
-
-#### Defined in
-
-[packages/core/src/hooks/public/usePublicEventLogo.ts:93](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/public/usePublicEventLogo.ts#L93)
-
-___
-
-### validateImage
-
-• `Optional` **validateImage**: `boolean`
-
-Whether to validate image existence (default: true)
-
-#### Defined in
-
-[packages/core/src/hooks/public/usePublicEventLogo.ts:95](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/public/usePublicEventLogo.ts#L95)
-
-___
-
-### generateFallbackText
-
-• `Optional` **generateFallbackText**: (`eventName`: `string`) => `string`
-
-Custom fallback text generator
-
-#### Type declaration
-
-▸ (`eventName`): `string`
-
-##### Parameters
-
-| Name | Type |
-| :------ | :------ |
-| `eventName` | `string` |
-
-##### Returns
-
-`string`
-
-#### Defined in
-
-[packages/core/src/hooks/public/usePublicEventLogo.ts:97](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/public/usePublicEventLogo.ts#L97)
-
-___
-
-### supabase
-
-• **supabase**: `default`\<`Database`, ``"public"``, ``"public"``, `never`, {}\>
-
-Supabase client instance (required)
-
-#### Defined in
-
-[packages/core/src/hooks/public/usePublicEventLogo.ts:99](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/public/usePublicEventLogo.ts#L99)

package/docs/api/interfaces/UsePublicEventLogoReturn.md

@@ -1,81 +0,0 @@
-[@jmruthers/pace-core - v0.5.102](../README.md) / [Exports](../modules.md) / UsePublicEventLogoReturn
-
-# Interface: UsePublicEventLogoReturn
-
-## Table of contents
-
-### Properties
-
-- [logoUrl](UsePublicEventLogoReturn.md#logourl)
-- [fallbackText](UsePublicEventLogoReturn.md#fallbacktext)
-- [isLoading](UsePublicEventLogoReturn.md#isloading)
-- [error](UsePublicEventLogoReturn.md#error)
-- [refetch](UsePublicEventLogoReturn.md#refetch)
-
-## Properties
-
-### logoUrl
-
-• **logoUrl**: ``null`` \| `string`
-
-The logo URL if available, null if not found or error
-
-#### Defined in
-
-[packages/core/src/hooks/public/usePublicEventLogo.ts:78](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/public/usePublicEventLogo.ts#L78)
-
-___
-
-### fallbackText
-
-• **fallbackText**: `string`
-
-Fallback text (event initials) if no logo is available
-
-#### Defined in
-
-[packages/core/src/hooks/public/usePublicEventLogo.ts:80](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/public/usePublicEventLogo.ts#L80)
-
-___
-
-### isLoading
-
-• **isLoading**: `boolean`
-
-Whether the logo is currently loading
-
-#### Defined in
-
-[packages/core/src/hooks/public/usePublicEventLogo.ts:82](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/public/usePublicEventLogo.ts#L82)
-
-___
-
-### error
-
-• **error**: ``null`` \| `Error`
-
-Any error that occurred during loading
-
-#### Defined in
-
-[packages/core/src/hooks/public/usePublicEventLogo.ts:84](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/public/usePublicEventLogo.ts#L84)
-
-___
-
-### refetch
-
-• **refetch**: () => `Promise`\<`void`\>
-
-Function to manually refetch the logo
-
-#### Type declaration
-
-▸ (): `Promise`\<`void`\>
-
-##### Returns
-
-`Promise`\<`void`\>
-
-#### Defined in
-
-[packages/core/src/hooks/public/usePublicEventLogo.ts:86](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/public/usePublicEventLogo.ts#L86)

package/src/hooks/public/usePublicEventLogo.ts

@@ -1,295 +0,0 @@
-/**
- * @file Public Event Logo Hook
- * @package @jmruthers/pace-core
- * @module Hooks/Public
- * @since 1.0.0
- *
- * A React hook for accessing public event logo URLs without authentication.
- * Provides logo URLs with fallback handling for public pages.
- *
- * Features:
- * - No authentication required
- * - Automatic fallback to event initials
- * - Caching for performance
- * - Error handling and loading states
- * - TypeScript support
- * - Image validation
- *
- * @example
- * ```tsx
- * import { usePublicEventLogo } from '@jmruthers/pace-core';
- *
- * function EventHeader() {
- *   const { logoUrl, fallbackText, isLoading, error } = usePublicEventLogo(
- *     eventId, 
- *     eventName, 
- *     organisationId
- *   );
- *
- *   if (isLoading) return <div>Loading logo...</div>;
- *   if (error) return <div>Error: {error.message}</div>;
- *
- *   return (
- *     <div>
- *       {logoUrl ? (
- *         <img src={logoUrl} alt={`${eventName} logo`} />
- *       ) : (
- *         <div className="logo-fallback">{fallbackText}</div>
- *       )}
- *     </div>
- *   );
- * }
- * ```
- *
- * @accessibility
- * - No direct accessibility concerns (hook)
- * - Enables accessible logo display with proper alt text
- * - Supports screen reader friendly fallbacks
- *
- * @security
- * - Only returns public-safe logo URLs
- * - Validates image existence before returning URL
- * - No sensitive information exposed
- * - Rate limiting applied at storage level
- *
- * @performance
- * - Built-in caching with TTL
- * - Image validation and optimization
- * - Minimal re-renders with stable references
- * - Lazy loading support
- *
- * @dependencies
- * - React 18+ - Hooks and effects
- * - @supabase/supabase-js - Storage integration
- * - Event types - Type definitions
- */
-
-import { useState, useEffect, useCallback, useMemo } from 'react';
-import type { SupabaseClient } from '@supabase/supabase-js';
-import type { Database } from '../../types/database';
-import { getPublicUrl } from '../../utils/storage/helpers';
-import { FileCategory } from '../../types/file-reference';
-
-// Simple in-memory cache for public data
-const publicDataCache = new Map<string, { data: any; timestamp: number; ttl: number }>();
-
-export interface UsePublicEventLogoReturn {
-  /** The logo URL if available, null if not found or error */
-  logoUrl: string | null;
-  /** Fallback text (event initials) if no logo is available */
-  fallbackText: string;
-  /** Whether the logo is currently loading */
-  isLoading: boolean;
-  /** Any error that occurred during loading */
-  error: Error | null;
-  /** Function to manually refetch the logo */
-  refetch: () => Promise<void>;
-}
-
-export interface UsePublicEventLogoOptions {
-  /** Cache TTL in milliseconds (default: 30 minutes) */
-  cacheTtl?: number;
-  /** Whether to enable caching (default: true) */
-  enableCache?: boolean;
-  /** Whether to validate image existence (default: true) */
-  validateImage?: boolean;
-  /** Custom fallback text generator */
-  generateFallbackText?: (eventName: string) => string;
-  /** Supabase client instance (required) */
-  supabase: SupabaseClient<Database>;
-}
-
-/**
- * Generate fallback text from event name (first letter of each word)
- */
-function defaultGenerateFallbackText(eventName: string): string {
-  if (!eventName) return 'EV';
-  
-  return eventName
-    .split(' ')
-    .map(word => word.charAt(0).toUpperCase())
-    .join('')
-    .substring(0, 3); // Max 3 characters
-}
-
-/**
- * Hook for accessing public event logo URLs
- * 
- * This hook provides access to event logo URLs without requiring
- * authentication. It includes fallback handling and image validation.
- * 
- * @param eventId - The event ID to fetch logo for
- * @param eventName - The event name for fallback text generation
- * @param organisationId - The organisation ID for storage path
- * @param options - Configuration options for caching and behavior
- * @returns Object containing logo URL, fallback text, loading state, error, and refetch function
- */
-export function usePublicEventLogo(
-  eventId: string | undefined,
-  eventName: string | undefined,
-  organisationId: string | undefined,
-  options: UsePublicEventLogoOptions
-): UsePublicEventLogoReturn {
-  const {
-    cacheTtl = 30 * 60 * 1000, // 30 minutes
-    enableCache = true,
-    validateImage = true,
-    generateFallbackText = defaultGenerateFallbackText,
-    supabase
-  } = options;
-
-  const [logoUrl, setLogoUrl] = useState<string | null>(null);
-  const [isLoading, setIsLoading] = useState<boolean>(false);
-  const [error, setError] = useState<Error | null>(null);
-
-  // Generate fallback text
-  const fallbackText = useMemo(() => {
-    return eventName ? generateFallbackText(eventName) : 'EV';
-  }, [eventName, generateFallbackText]);
-
-  const fetchLogo = useCallback(async (): Promise<void> => {
-    if (!eventId || !organisationId || !supabase) {
-      setLogoUrl(null);
-      setIsLoading(false);
-      return;
-    }
-
-    // Validate UUID format for organisationId to prevent database errors
-    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-    if (!uuidRegex.test(organisationId)) {
-      console.warn('[usePublicEventLogo] Invalid organisationId format (not a valid UUID):', organisationId);
-      // Don't return early - let the database handle the validation
-      // This allows for more graceful error handling
-    }
-
-    // Check cache first
-    const cacheKey = `public_logo_${eventId}_${organisationId}`;
-    if (enableCache) {
-      const cached = publicDataCache.get(cacheKey);
-      if (cached && Date.now() - cached.timestamp < cached.ttl) {
-        setLogoUrl(cached.data);
-        setIsLoading(false);
-        setError(null);
-        return;
-      }
-    }
-
-    try {
-      setIsLoading(true);
-      setError(null);
-
-      // Get event logo from file_references using new RPC function
-      const { data, error: rpcError } = await (supabase as any)
-        .rpc('data_file_reference_by_category_list', {
-          p_table_name: 'event',
-          p_record_id: eventId,
-          p_category: FileCategory.EVENT_LOGOS,
-          p_organisation_id: organisationId
-        });
-
-      if (rpcError) {
-        throw new Error(rpcError.message || 'Failed to fetch logo');
-      }
-
-      if (!data || data.length === 0 || !data[0]?.file_path) {
-        setLogoUrl(null);
-        return;
-      }
-
-      // Get the file path from the RPC response
-      const logoPath = data[0].file_path;
-      const isPublic = data[0].is_public ?? true; // Event logos should be public
-
-      // Generate public URL using bucket-aware helper (public-files bucket for public files)
-      const logoUrl = getPublicUrl(supabase, logoPath, isPublic);
-
-      // Validate image existence if requested
-      if (validateImage) {
-        try {
-          const response = await fetch(logoUrl, { method: 'HEAD' });
-          if (!response.ok) {
-            console.warn('[usePublicEventLogo] Logo URL not accessible:', logoUrl);
-            setLogoUrl(null);
-            return;
-          }
-        } catch (fetchError) {
-          console.warn('[usePublicEventLogo] Error validating logo URL:', fetchError);
-          setLogoUrl(null);
-          return;
-        }
-      }
-
-      setLogoUrl(logoUrl);
-
-      // Cache the result
-      if (enableCache) {
-        publicDataCache.set(cacheKey, {
-          data: logoUrl,
-          timestamp: Date.now(),
-          ttl: cacheTtl
-        });
-      }
-
-    } catch (err) {
-      console.error('[usePublicEventLogo] Error fetching logo:', err);
-      const error = err instanceof Error ? err : new Error('Unknown error occurred');
-      setError(error);
-      setLogoUrl(null);
-    } finally {
-      setIsLoading(false);
-    }
-  }, [eventId, organisationId, supabase, cacheTtl, enableCache, validateImage]);
-
-  // Fetch logo when parameters change
-  useEffect(() => {
-    if (eventId && organisationId) {
-      fetchLogo();
-    } else {
-      setLogoUrl(null);
-      setIsLoading(false);
-      setError(null);
-    }
-  }, [fetchLogo, eventId, organisationId]);
-
-  const refetch = useCallback(async (): Promise<void> => {
-    if (!eventId || !organisationId) return;
-    
-    // Clear cache for this logo
-    if (enableCache) {
-      const cacheKey = `public_logo_${eventId}_${organisationId}`;
-      publicDataCache.delete(cacheKey);
-    }
-    await fetchLogo();
-  }, [fetchLogo, eventId, organisationId, enableCache]);
-
-  return {
-    logoUrl,
-    fallbackText,
-    isLoading,
-    error,
-    refetch
-  };
-}
-
-/**
- * Clear all cached public logo data
- * Useful for testing or when you need to force refresh all data
- */
-export function clearPublicLogoCache(): void {
-  for (const [key] of publicDataCache) {
-    if (key.startsWith('public_logo_')) {
-      publicDataCache.delete(key);
-    }
-  }
-}
-
-/**
- * Get cache statistics for debugging
- */
-export function getPublicLogoCacheStats(): { size: number; keys: string[] } {
-  const keys = Array.from(publicDataCache.keys()).filter(key => key.startsWith('public_logo_'));
-  return {
-    size: keys.length,
-    keys
-  };
-}