@jmruthers/pace-core 0.2.4

package/dist/unified-CM7T0aTK.d.ts

@@ -0,0 +1,198 @@
+/**
+ * @file Unified types for PACE Core
+ * @package @jmruthers/pace-core
+ * @module unified
+ * @since 0.1.0
+ */
+/**
+ * @file Unified Types for DataTable
+ * @package @jmruthers/pace-core
+ * @module Types
+ * @since 0.3.0
+ */
+declare enum AuthErrorCode {
+    UNKNOWN_ERROR = "UNKNOWN_ERROR",
+    INVALID_CREDENTIALS = "INVALID_CREDENTIALS",
+    USER_NOT_FOUND = "USER_NOT_FOUND",
+    EMAIL_NOT_CONFIRMED = "EMAIL_NOT_CONFIRMED",
+    PASSWORD_TOO_WEAK = "PASSWORD_TOO_WEAK",
+    WEAK_PASSWORD = "WEAK_PASSWORD",
+    RATE_LIMITED = "RATE_LIMITED",
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED",
+    SESSION_EXPIRED = "SESSION_EXPIRED",
+    PERMISSION_DENIED = "PERMISSION_DENIED",
+    NETWORK_ERROR = "NETWORK_ERROR"
+}
+declare enum PermissionErrorCode {
+    INSUFFICIENT_PERMISSIONS = "INSUFFICIENT_PERMISSIONS",
+    INVALID_PERMISSION = "INVALID_PERMISSION",
+    PERMISSION_CHECK_FAILED = "PERMISSION_CHECK_FAILED",
+    ACCESS_DENIED = "ACCESS_DENIED"
+}
+declare enum AccessLevel {
+    NONE = "none",
+    VIEWER = "viewer",
+    PARTICIPANT = "participant",
+    EDITOR = "editor",
+    PLANNER = "planner",
+    ADMIN = "admin",
+    SUPER_ADMIN = "super_admin",
+    SUPER = "super"
+}
+type UserId = string & {
+    __brand: 'UserId';
+};
+type SessionToken = string & {
+    __brand: 'SessionToken';
+};
+type PermissionString = string & {
+    __brand: 'PermissionString';
+};
+type RequestId = string & {
+    __brand: 'RequestId';
+};
+declare function createUserId(id: string): UserId;
+declare function createSessionToken(token: string): SessionToken;
+declare function createPermissionString(permission: string): PermissionString;
+declare function createRequestId(id: string): RequestId;
+declare function isUserId(value: unknown): value is UserId;
+declare function isSessionToken(value: unknown): value is SessionToken;
+declare function isPermissionString(value: unknown): value is PermissionString;
+declare function isRequestId(value: unknown): value is RequestId;
+type PermissionMap = Record<string, boolean>;
+interface PermissionContext {
+    eventId?: string;
+    appName?: string;
+    userId?: string;
+}
+interface AuthError extends Error {
+    __isAuthError: true;
+    name: 'AuthError';
+    message: string;
+    code: AuthErrorCode;
+    user_message: string;
+    timestamp: number;
+}
+interface PermissionError extends Error {
+    __isPermissionError: true;
+    name: 'PermissionError';
+    message: string;
+    code: PermissionErrorCode;
+    timestamp: number;
+}
+interface ThemeColors {
+    primary: string;
+    secondary: string;
+    hover?: string;
+    active?: string;
+    bgSoft?: string;
+}
+interface EventTheme {
+    mid: ThemeColors;
+    light: ThemeColors;
+}
+interface Event {
+    id: string;
+    event_id: string;
+    event_name: string;
+    event_code?: string;
+    organisation_id: string;
+    event_date?: string;
+    event_days?: number;
+    event_venue?: string;
+    event_participants?: number;
+    is_visible?: boolean;
+    event_logo?: string;
+    event_colours?: Record<string, unknown> | null;
+    event_col_d1?: string;
+    event_col_d2?: string;
+    event_col_m1?: string;
+    event_col_m2?: string;
+    event_col_l1?: string;
+    event_col_l2?: string;
+    event_news?: string;
+    event_billing?: string;
+    event_catering_email?: string;
+    event_email?: string;
+    event_footer?: string;
+    event_rounddown?: number;
+    event_youthmultiplier?: number;
+    event_typicalunit?: number;
+    created_at: string;
+    updated_at: string;
+    created_by?: string;
+    updated_by?: string;
+    name?: string;
+    description?: string;
+    start_date?: string;
+    end_date?: string;
+    theme_colors?: EventTheme;
+}
+interface EventContextType {
+    selectedEvent: Event | null;
+    currentEvent: Event | null;
+    events: Event[];
+    isLoading: boolean;
+    error: string | null;
+    selectEvent: (event: Event) => void;
+    setCurrentEvent: (event: Event | null) => void;
+    clearSelection: () => void;
+    refreshEvents: () => Promise<void>;
+    createEvent: (event: Partial<Event>) => Promise<Event>;
+    updateEvent: (id: string, updates: Partial<Event>) => Promise<Event>;
+    deleteEvent: (id: string) => Promise<void>;
+}
+interface UserPermissions {
+    user_id: UserId;
+    accessLevel: AccessLevel;
+    permissions: PermissionMap;
+    roles: string[];
+}
+interface User {
+    id: string;
+    email?: string;
+    created_at: string;
+    updated_at: string;
+    email_confirmed_at?: string;
+    last_sign_in_at?: string;
+    user_metadata?: Record<string, unknown>;
+    app_metadata?: Record<string, unknown>;
+}
+interface Session {
+    access_token: string;
+    refresh_token?: string;
+    expires_in: number;
+    expires_at: number;
+    token_type: string;
+    user: User;
+    provider_token?: string;
+    provider_refresh_token?: string;
+}
+interface DataRecord {
+    id: string | number;
+    [key: string]: unknown;
+}
+interface DataTableAction<T = unknown> {
+    label: string;
+    onClick: (row: T) => void;
+    testId?: string;
+    disabled?: boolean | ((row: T) => boolean);
+    variant?: 'primary' | 'secondary' | 'destructive';
+}
+interface DataTableColumn<T = unknown> {
+    id?: string;
+    key: string;
+    label: string;
+    sortable?: boolean;
+    filterable?: boolean;
+    accessorKey?: keyof T;
+    accessorFn?: (row: T) => unknown;
+    cell?: (value: unknown, row: T) => React.ReactNode;
+    header?: React.ReactNode;
+    enableSorting?: boolean;
+    enableColumnFilter?: boolean;
+    enableGrouping?: boolean;
+    enableHiding?: boolean;
+}
+
+export { type AuthError as A, type DataRecord as D, type EventTheme as E, type PermissionError as P, type RequestId as R, type Session as S, type ThemeColors as T, type User as U, type UserPermissions as a, type PermissionString as b, AccessLevel as c, AuthErrorCode as d, PermissionErrorCode as e, type UserId as f, type SessionToken as g, createUserId as h, createSessionToken as i, createPermissionString as j, createRequestId as k, isUserId as l, isSessionToken as m, isPermissionString as n, isRequestId as o, type PermissionMap as p, type PermissionContext as q, type Event as r, type EventContextType as s, type DataTableAction as t, type DataTableColumn as u };

package/dist/useComponentPerformance-DE9l5RkL.d.ts

@@ -0,0 +1,11 @@
+interface PerformanceConfig {
+    componentName: string;
+    enableLogging?: boolean;
+    threshold?: number;
+}
+declare function useComponentPerformance({ componentName, enableLogging, threshold }: PerformanceConfig): {
+    renderCount: number;
+    componentName: string;
+};
+
+export { useComponentPerformance as u };

package/dist/usePublicRouteParams-B6i0KtXW.d.ts

@@ -0,0 +1,477 @@
+import { e as OrganisationRole, f as OrganisationPermission, g as SuperAdminContext } from './organisation-CO3Sh3_D.js';
+import { r as Event } from './unified-CM7T0aTK.js';
+import { SupabaseClient } from '@supabase/supabase-js';
+import { D as Database } from './database-C3Szpi5J.js';
+
+/**
+ * @file useOrganisationPermissions Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/useOrganisationPermissions
+ * @since 0.4.0
+ *
+ * Hook for managing organisation-specific permissions and role validation.
+ * Provides secure access to user's role and permissions within organisations.
+ *
+ * @example
+ * ```tsx
+ * function OrganisationComponent() {
+ *   const {
+ *     isOrgAdmin,
+ *     canManageMembers,
+ *     userRole,
+ *     hasOrganisationAccess
+ *   } = useOrganisationPermissions();
+ *
+ *   return (
+ *     <div>
+ *       {isOrgAdmin && <AdminPanel />}
+ *       {canManageMembers && <MemberManagement />}
+ *       <p>Your role: {userRole}</p>
+ *     </div>
+ *   );
+ * }
+ *
+ * // For specific organisation
+ * function MultiOrgComponent() {
+ *   const permissions = useOrganisationPermissions('org-123');
+ *
+ *   if (!permissions.hasOrganisationAccess) {
+ *     return <div>No access to this organisation</div>;
+ *   }
+ *
+ *   return <div>Role in org-123: {permissions.userRole}</div>;
+ * }
+ * ```
+ *
+ * @security
+ * - Validates user membership in organisation
+ * - Provides role-based permission checks
+ * - Ensures secure access to organisation data
+ * - Real-time permission validation
+ */
+
+interface UseOrganisationPermissionsReturn {
+    /** User's role in the organisation */
+    userRole: OrganisationRole | 'no_access';
+    /** Whether user has organisation admin role */
+    isOrgAdmin: boolean;
+    /** Whether user is a super admin */
+    isSuperAdmin: boolean;
+    /** Whether user can moderate content */
+    canModerate: boolean;
+    /** Whether user can manage members */
+    canManageMembers: boolean;
+    /** Whether user can manage organisation settings */
+    canManageSettings: boolean;
+    /** Whether user can manage events */
+    canManageEvents: boolean;
+    /** Whether user has any admin privileges */
+    hasAdminPrivileges: boolean;
+    /** Whether user has access to the organisation */
+    hasOrganisationAccess: boolean;
+    /** Check if user has specific permission */
+    hasPermission: (permission: OrganisationPermission) => boolean;
+    /** Get all permissions for the user */
+    getAllPermissions: () => OrganisationPermission[];
+    /** Organisation ID being checked */
+    organisationId: string;
+}
+/**
+ * Hook to access organisation-specific permissions and roles
+ *
+ * @param orgId - Optional organisation ID. Defaults to currently selected organisation
+ * @returns Organisation permissions and role information
+ */
+declare function useOrganisationPermissions(orgId?: string): UseOrganisationPermissionsReturn;
+
+/**
+ * @file Organisation Security Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/OrganisationSecurity
+ * @since 0.4.0
+ *
+ * Security-focused hook for organisation access validation and super admin functionality.
+ * Provides utilities for validating user access to organisations and checking permissions.
+ */
+
+interface OrganisationSecurityHook {
+    superAdminContext: SuperAdminContext;
+    validateOrganisationAccess: (orgId: string) => Promise<boolean>;
+    hasMinimumRole: (minRole: string, orgId?: string) => boolean;
+    canAccessChildOrganisations: (orgId?: string) => boolean;
+    hasPermission: (permission: string, orgId?: string) => Promise<boolean>;
+    getUserPermissions: (orgId?: string) => Promise<string[]>;
+    logOrganisationAccess: (action: string, details?: any) => Promise<void>;
+    ensureOrganisationAccess: (orgId: string) => Promise<void>;
+    validateUserAccess: (userId: string, orgId: string) => Promise<boolean>;
+}
+declare const useOrganisationSecurity: () => OrganisationSecurityHook;
+
+/**
+ * @file useAppConfig Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/useAppConfig
+ * @since 0.4.0
+ *
+ * Hook for accessing app configuration like direct access support and event requirements.
+ * This is a convenience hook that extracts app config from the UnifiedAuthProvider.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { supportsDirectAccess, requiresEvent, isLoading } = useAppConfig();
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <div>
+ *       {supportsDirectAccess && (
+ *         <div>This app supports direct access!</div>
+ *       )}
+ *       {requiresEvent && (
+ *         <EventSelector />
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+interface UseAppConfigReturn {
+    supportsDirectAccess: boolean;
+    requiresEvent: boolean;
+    isLoading: boolean;
+    appName: string;
+}
+/**
+ * Hook to access app configuration
+ * Works in both authenticated and public contexts
+ * @returns App configuration and loading state
+ */
+declare function useAppConfig(): UseAppConfigReturn;
+
+/**
+ * @file Public Event Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/Public
+ * @since 1.0.0
+ *
+ * A React hook for accessing public event data without authentication.
+ * Provides event information by event_code for public pages.
+ *
+ * Features:
+ * - No authentication required
+ * - Caching for performance
+ * - Error handling and loading states
+ * - TypeScript support
+ * - Automatic refetch capabilities
+ *
+ * @example
+ * ```tsx
+ * import { usePublicEvent } from '@jmruthers/pace-core';
+ *
+ * function PublicEventPage() {
+ *   const { eventCode } = usePublicRouteParams();
+ *   const { event, isLoading, error, refetch } = usePublicEvent(eventCode);
+ *
+ *   if (isLoading) return <div>Loading event...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   if (!event) return <div>Event not found</div>;
+ *
+ *   return (
+ *     <div>
+ *       <h1>{event.event_name}</h1>
+ *       <p>Date: {event.event_date}</p>
+ *       <p>Venue: {event.event_venue}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @accessibility
+ * - No direct accessibility concerns (hook)
+ * - Enables accessible public event display
+ * - Supports screen reader friendly loading states
+ *
+ * @security
+ * - Only returns public-safe event data
+ * - Validates event_code before querying
+ * - No sensitive information exposed
+ * - Rate limiting applied at database level
+ *
+ * @performance
+ * - Built-in caching with TTL
+ * - Minimal re-renders with stable references
+ * - Lazy loading support
+ * - Error boundary integration
+ *
+ * @dependencies
+ * - React 18+ - Hooks and effects
+ * - @supabase/supabase-js - Database integration
+ * - Event types - Type definitions
+ */
+
+interface UsePublicEventReturn {
+    /** The event data, null if not loaded or not found */
+    event: Event | null;
+    /** Whether the data is currently loading */
+    isLoading: boolean;
+    /** Any error that occurred during loading */
+    error: Error | null;
+    /** Function to manually refetch the data */
+    refetch: () => Promise<void>;
+}
+interface UsePublicEventOptions {
+    /** Cache TTL in milliseconds (default: 5 minutes) */
+    cacheTtl?: number;
+    /** Whether to enable caching (default: true) */
+    enableCache?: boolean;
+}
+/**
+ * Hook for accessing public event data by event_code
+ *
+ * This hook provides access to public event information without requiring
+ * authentication. It includes caching, error handling, and loading states.
+ *
+ * @param eventCode - The event code to look up
+ * @param options - Configuration options for caching and behavior
+ * @returns Object containing event data, loading state, error, and refetch function
+ */
+declare function usePublicEvent(eventCode: string, options?: UsePublicEventOptions): UsePublicEventReturn;
+/**
+ * Clear all cached public event data
+ * Useful for testing or when you need to force refresh all data
+ */
+declare function clearPublicEventCache(): void;
+/**
+ * Get cache statistics for debugging
+ */
+declare function getPublicEventCacheStats(): {
+    size: number;
+    keys: string[];
+};
+
+/**
+ * @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
+ */
+
+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>;
+}
+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>;
+}
+/**
+ * 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
+ */
+declare function usePublicEventLogo(eventId: string | undefined, eventName: string | undefined, organisationId: string | undefined, options: UsePublicEventLogoOptions): UsePublicEventLogoReturn;
+/**
+ * Clear all cached public logo data
+ * Useful for testing or when you need to force refresh all data
+ */
+declare function clearPublicLogoCache(): void;
+/**
+ * Get cache statistics for debugging
+ */
+declare function getPublicLogoCacheStats(): {
+    size: number;
+    keys: string[];
+};
+
+/**
+ * @file Public Route Params Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/Public
+ * @since 1.0.0
+ *
+ * A React hook for extracting and validating public route parameters.
+ * Provides event code extraction and validation for public pages.
+ *
+ * Features:
+ * - URL parameter extraction
+ * - Event code validation
+ * - TypeScript support
+ * - Error handling
+ * - Route pattern support
+ *
+ * @example
+ * ```tsx
+ * import { usePublicRouteParams } from '@jmruthers/pace-core';
+ *
+ * function PublicEventPage() {
+ *   const { eventCode, eventId, event, error, isLoading } = usePublicRouteParams();
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   if (!event) return <div>Event not found</div>;
+ *
+ *   return (
+ *     <div>
+ *       <h1>{event.event_name}</h1>
+ *       <p>Event Code: {eventCode}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @accessibility
+ * - No direct accessibility concerns (hook)
+ * - Enables accessible route parameter handling
+ * - Supports screen reader friendly error states
+ *
+ * @security
+ * - Validates event codes before processing
+ * - Sanitizes URL parameters
+ * - No sensitive information exposed
+ * - Rate limiting applied at route level
+ *
+ * @performance
+ * - Minimal re-renders with stable references
+ * - Efficient parameter extraction
+ * - Caching integration
+ *
+ * @dependencies
+ * - React 18+ - Hooks and effects
+ * - React Router - URL parameter extraction
+ * - Event types - Type definitions
+ */
+
+interface UsePublicRouteParamsReturn {
+    /** The event code from the URL */
+    eventCode: string | null;
+    /** The event ID (resolved from event code) */
+    eventId: string | null;
+    /** The full event object */
+    event: Event | null;
+    /** Whether the route parameters are being processed */
+    isLoading: boolean;
+    /** Any error that occurred during processing */
+    error: Error | null;
+    /** Function to manually refetch the event data */
+    refetch: () => Promise<void>;
+}
+interface UsePublicRouteParamsOptions {
+    /** Whether to automatically fetch event data (default: true) */
+    fetchEventData?: boolean;
+    /** Custom event code parameter name (default: 'eventCode') */
+    eventCodeParam?: string;
+    /** Whether to validate event code format (default: true) */
+    validateEventCode?: boolean;
+}
+/**
+ * Hook for extracting and validating public route parameters
+ *
+ * This hook extracts event codes from URL parameters and optionally
+ * fetches the corresponding event data. It provides validation and
+ * error handling for public routes.
+ *
+ * @param options - Configuration options for behavior
+ * @returns Object containing route parameters, event data, loading state, error, and refetch function
+ */
+declare function usePublicRouteParams(options?: UsePublicRouteParamsOptions): UsePublicRouteParamsReturn;
+/**
+ * Hook for extracting just the event code without fetching event data
+ * Useful when you only need the event code and will fetch data separately
+ */
+declare function usePublicEventCode(eventCodeParam?: string): {
+    eventCode: string | null;
+    error: Error | null;
+};
+/**
+ * Utility function to generate public route paths
+ */
+declare function generatePublicRoutePath(eventCode: string, pageName?: string): string;
+/**
+ * Utility function to extract event code from a public route path
+ */
+declare function extractEventCodeFromPath(path: string): string | null;
+
+export { type OrganisationSecurityHook as O, type UsePublicEventReturn as U, useOrganisationSecurity as a, useAppConfig as b, usePublicEvent as c, clearPublicEventCache as d, usePublicEventLogo as e, clearPublicLogoCache as f, getPublicEventCacheStats as g, getPublicLogoCacheStats as h, usePublicRouteParams as i, usePublicEventCode as j, generatePublicRoutePath as k, extractEventCodeFromPath as l, type UsePublicEventOptions as m, type UsePublicEventLogoReturn as n, type UsePublicEventLogoOptions as o, type UsePublicRouteParamsReturn as p, type UseOrganisationPermissionsReturn as q, type UseAppConfigReturn as r, useOrganisationPermissions as u };