@jmruthers/pace-core 0.5.181 → 0.5.182

package/docs/api-reference/hooks.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T12:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Hooks API Reference
@@ -14,23 +14,77 @@ This section provides detailed API documentation for all React hooks in `@jmruth
 
 ### useUnifiedAuth
 
-A comprehensive hook that combines authentication and event access management.
+A comprehensive hook that combines authentication, organisation context, event access management, and inactivity tracking.
 
 ```typescript
-interface UseUnifiedAuthReturn {
+interface UnifiedAuthContextType {
+  // Auth state
   user: User | null;
   session: Session | null;
-  loading: boolean;
-  error: AuthError | null;
-  signIn: (credentials: SignInCredentials) => Promise<void>;
-  signUp: (credentials: SignUpCredentials) => Promise<void>;
-  signOut: () => Promise<void>;
-  resetPassword: (email: string) => Promise<void>;
-  updatePassword: (password: string) => Promise<void>;
+  isAuthenticated: boolean;
+  authLoading: boolean;
+  authError: AuthError | null;
+  error: AuthError | null; // Alias for authError
+  supabase: SupabaseClient | null;
+  
+  // Auth methods
+  signIn: (email: string, password?: string) => Promise<{ error: AuthError | null }>;
+  signUp: (email: string, password: string) => Promise<{ error: AuthError | null }>;
+  signOut: () => Promise<{ error: AuthError | null }>;
+  resetPassword: (email: string) => Promise<{ error: AuthError | null }>;
+  updatePassword: (password: string) => Promise<{ error: AuthError | null }>;
+  refreshSession: () => Promise<{ error: AuthError | null }>;
+
+  // Organisation state
+  selectedOrganisation: Organisation | null;
+  organisations: Organisation[];
+  userMemberships: OrganisationMembership[];
+  organisationLoading: boolean;
+  organisationError: Error | null;
+  hasValidOrganisationContext: boolean;
+  isContextReady: boolean;
+  
+  // Organisation methods
+  switchOrganisation: (orgId: string) => Promise<void>;
+  getUserRole: (orgId?: string) => string;
+  validateOrganisationAccess: (orgId: string) => boolean;
+  refreshOrganisations: () => Promise<void>;
+  ensureOrganisationContext: () => Organisation;
+  isOrganisationSecure: () => boolean;
+  getPrimaryOrganisation: () => Organisation | null;
+
+  // Event state
   events: Event[];
   selectedEvent: Event | null;
+  eventLoading: boolean;
+  eventError: Error | null;
+  
+  // Event methods
   setSelectedEvent: (event: Event | null) => void;
-  hasEventAccess: (eventId: string) => boolean;
+  refreshEvents: () => Promise<void>;
+
+  // Inactivity state
+  showInactivityWarning: boolean;
+  inactivityTimeRemaining: number;
+  isIdle: boolean;
+  timeRemaining: number;
+  showWarning: boolean;
+  isTracking: boolean;
+  
+  // Inactivity methods
+  resetActivity: () => void;
+  startTracking: () => void;
+  stopTracking: () => void;
+  handleIdleLogout: () => Promise<void>;
+  handleStaySignedIn: () => void;
+  handleSignOutNow: () => Promise<void>;
+
+  // Additional properties
+  appName: string;
+  appConfig: { requires_event: boolean } | null;
+  isLoading: boolean;
+  hasErrors: boolean;
+  sessionRestorationTimedOut: boolean;
 }
 ```
 
@@ -43,18 +97,22 @@ function App() {
   const {
     user,
     session,
-    loading,
-    error,
+    isLoading,
+    authError,
     signIn,
     signOut,
+    selectedOrganisation,
+    organisations,
     events,
     selectedEvent,
     setSelectedEvent,
-    hasEventAccess,
+    showWarning,
+    handleStaySignedIn,
+    handleSignOutNow,
   } = useUnifiedAuth();
 
-  if (loading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
+  if (isLoading) return <div>Loading...</div>;
+  if (authError) return <div>Error: {authError.message}</div>;
 
   return (
     <div>
@@ -504,6 +562,78 @@ function Dropdown() {
 
 ## Performance Hooks
 
+### usePerformanceMonitor
+
+Monitor overall application performance metrics.
+
+```typescript
+interface PerformanceData {
+  renderTime: number;
+  memoryUsage: number;
+  componentCount: number;
+}
+
+function usePerformanceMonitor(): PerformanceData;
+```
+
+#### Usage
+
+```tsx
+import { usePerformanceMonitor } from '@jmruthers/pace-core';
+
+function PerformanceDashboard() {
+  const metrics = usePerformanceMonitor();
+  
+  return (
+    <div>
+      <p>Render time: {metrics.renderTime}ms</p>
+      <p>Memory usage: {metrics.memoryUsage}MB</p>
+      <p>Components: {metrics.componentCount}</p>
+    </div>
+  );
+}
+```
+
+### useOperationPerformance
+
+Monitor performance of specific operations with budget tracking.
+
+```typescript
+function useOperationPerformance(
+  operationName: string,
+  budgetName?: string
+): {
+  start: () => void;
+  end: () => void;
+  duration: number;
+  isOverBudget: boolean;
+};
+```
+
+#### Usage
+
+```tsx
+import { useOperationPerformance } from '@jmruthers/pace-core';
+
+function ExpensiveOperation() {
+  const { start, end, duration, isOverBudget } = useOperationPerformance(
+    'data-processing',
+    'data-processing-budget'
+  );
+
+  const handleProcess = async () => {
+    start();
+    await processData();
+    end();
+    
+    if (isOverBudget) {
+      console.warn('Operation exceeded budget');
+    }
+  };
+
+  return <button onClick={handleProcess}>Process</button>;
+}
+```
 
 ## Hook Composition
 
@@ -1290,4 +1420,4 @@ All hooks include comprehensive testing:
 - **Performance Tests**: Memory leak detection
 - **Type Safety**: TypeScript validation
 
-For more information about testing hooks, see the [Testing Guide](../best-practices/testing.md). 
+For more information about testing hooks, see the [Testing Guide](../testing/README.md). 

package/docs/api-reference/providers.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T20:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Providers API Reference
@@ -21,7 +21,7 @@ interface UnifiedAuthProviderProps {
   children: React.ReactNode;
   persistState?: boolean;
   requireOrganisationContext?: boolean;
-  enableRBAC?: boolean;
+  // Note: RBAC is always enabled - no prop needed
   onAuthStateChange?: (event: AuthChangeEvent, session: Session | null) => void;
   
   // Inactivity auto-logout configuration - MANDATORY for security
@@ -56,7 +56,6 @@ function App() {
     <UnifiedAuthProvider 
       supabaseClient={supabase} 
       appName="my-app"
-      enableRBAC={true}
       requireOrganisationContext={true}
       idleTimeoutMs={30 * 60 * 1000}  // Required: 30 minutes
       warnBeforeMs={5 * 60 * 1000}    // Required: 5 minutes warning
@@ -76,7 +75,7 @@ function App() {
 | `appName` | `string` | Required | Name of your application |
 | `persistState` | `boolean` | `true` | Persist auth state across sessions |
 | `requireOrganisationContext` | `boolean` | `true` | Require organisation context for security |
-| `enableRBAC` | `boolean` | `false` | Enable the RBAC system |
+| RBAC | Always enabled | - | RBAC is always enabled, no configuration needed |
 | `onAuthStateChange` | `function` | `undefined` | Callback for auth state changes |
 | `idleTimeoutMs` | `number` | **Required** | Inactivity timeout in milliseconds (e.g., `30 * 60 * 1000` for 30 minutes) |
 | `warnBeforeMs` | `number` | **Required** | Warning time before logout in milliseconds (e.g., `5 * 60 * 1000` for 5 minutes) |
@@ -572,6 +571,62 @@ Use context splitting when possible to prevent unnecessary re-renders.
 
 Only pass required props to avoid unnecessary re-renders and complexity.
 
+## ♿ Accessibility
+
+Providers support accessibility:
+
+- **Keyboard navigation** - All provider-managed components support keyboard navigation
+- **Screen reader support** - Providers ensure proper ARIA attributes and roles
+- **Focus management** - Providers handle focus management correctly
+- **Error announcements** - Error states are properly announced to screen readers
+- **Loading states** - Loading indicators are accessible and announced
+
+### Accessibility Best Practices
+
+1. **Test provider composition** - Verify accessibility works with provider hierarchy
+2. **Check focus management** - Ensure focus is properly managed during state changes
+3. **Test with screen readers** - Verify provider-managed content works with assistive technologies
+4. **Verify ARIA attributes** - Ensure providers set appropriate ARIA attributes
+5. **Test keyboard navigation** - Verify all provider-managed interactions are keyboard accessible
+
+## ⚠️ Edge Cases
+
+### Provider Initialization Failures
+
+When providers fail to initialize:
+- Verify all required props are provided
+- Check Supabase client is properly configured
+- Review provider dependencies and order
+- Test with minimal configuration
+- Verify environment variables are set correctly
+
+### Context Not Available
+
+When provider context is not available:
+- Verify provider is properly mounted in component tree
+- Check provider order (UnifiedAuthProvider → OrganisationProvider → EventProvider)
+- Review component hierarchy for missing providers
+- Test with provider composition examples
+- Verify hooks are called within provider context
+
+### State Synchronization Issues
+
+When provider state is out of sync:
+- Check for multiple provider instances
+- Verify provider state updates correctly
+- Review state management logic
+- Test with rapid state changes
+- Check for race conditions in state updates
+
+### Inactivity Tracking Edge Cases
+
+When inactivity tracking fails:
+- Verify mandatory props (idleTimeoutMs, warnBeforeMs, onIdleLogout) are provided
+- Check localStorage is available and working
+- Review cross-tab synchronization
+- Test with different browser environments
+- Verify inactivity events are properly monitored
+
 ## What's Next?
 
 - **[Components](./components.md)** - All UI components

package/docs/api-reference/rpc-functions.md

@@ -0,0 +1,397 @@
+---
+lastUpdated: 2025-11-18T12:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
+---
+
+# RPC Functions API Reference
+
+This document provides an overview of RPC (Remote Procedure Call) functions in `pace-core` and how to use them. RPC functions follow strict naming conventions and security standards as defined in the [API & RPC Standard](../standards/02-api-and-rpc-standard.md).
+
+## Overview
+
+RPC functions are PostgreSQL functions that provide a secure, standardized way to interact with the database. They enforce Row Level Security (RLS), validate organisation context, and return consistent result shapes.
+
+## Naming Convention
+
+All RPC functions follow the `<family>_<domain>_<verb>` pattern:
+
+- **`data_*`** prefix for read operations (e.g., `data_file_reference_list`, `data_user_organisations_get`)
+- **`app_*`** prefix for write operations (e.g., `app_cake_dish_create`, `app_file_reference_create`)
+- **`rbac_*`** prefix for RBAC operations (exception to standard pattern, e.g., `rbac_permission_check`, `rbac_role_grant`)
+- **`util_*`** prefix for utility functions (e.g., `util_app_resolve`)
+- **CRUD verbs**: `create`, `read`, `get`, `list`, `update`, `delete`
+- **Bulk operations**: Use `_bulk` suffix (e.g., `app_cake_dish_create_bulk`)
+
+**Note**: The `rbac_*` prefix is an exception to the standard `data_*`/`app_*` pattern. RBAC functions use their own prefix for clarity and consistency within the RBAC system.
+
+### Examples
+
+```sql
+-- Read operations (data_*)
+data_file_reference_list(...)
+data_file_reference_get(...)
+data_cake_dishes_list(...)
+data_event_list(...)
+
+-- Write operations (app_*)
+app_cake_dish_create(...)
+app_file_reference_create(...)
+app_cake_dish_update(...)
+app_cake_dish_delete(...)
+
+-- Bulk operations
+app_cake_dish_create_bulk(...)
+```
+
+## Result Shape
+
+RPC functions conceptually follow the `ApiResult<T>` shape as defined in the [API & RPC Standard](../standards/02-api-and-rpc-standard.md), but are wrapped by Supabase's client into the standard `{ data, error }` format:
+
+```typescript
+// Conceptual ApiResult shape (from standard)
+type ApiResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; error: ApiError };
+
+type ApiError = {
+  code: string;
+  message: string;
+  details?: object;
+};
+
+// Actual Supabase RPC response format
+type SupabaseRPCResponse<T> = {
+  data: T | null;
+  error: PostgrestError | null;
+};
+```
+
+**Note**: Supabase RPCs return data directly (as TABLE or scalar types), and the Supabase client wraps them in `{ data, error }` format. Error handling should check the `error` field rather than expecting an `ApiResult` wrapper.
+
+### Usage Example
+
+```typescript
+import { supabase } from './supabaseClient';
+
+// Call RPC function
+const { data, error } = await supabase.rpc('data_file_reference_list', {
+  p_table_name: 'pace_person',
+  p_record_id: personId,
+  p_organisation_id: orgId
+});
+
+if (error) {
+  // Handle error - Supabase wraps errors in the error field
+  console.error('RPC error:', error.message, error.code);
+  return;
+}
+
+// Use data - data is null if error occurred
+if (data) {
+  const fileReferences = data;
+}
+```
+
+## RPC Rules
+
+As per the [API & RPC Standard](../standards/02-api-and-rpc-standard.md):
+
+1. **Read RPCs never mutate** - `data_*` functions are read-only
+2. **Write RPCs should be idempotent** - `app_*` functions can be safely retried
+3. **Never accept dynamic SQL** - All queries are parameterized
+4. **Must enforce RLS + tenant boundaries** - Organisation context is always validated
+5. **Errors must be user-safe** - No sensitive information in error messages
+
+## Core RPC Functions
+
+### File Reference System
+
+Documented in [File Reference System Guide](../implementation-guides/file-reference-system.md):
+
+**Note**: File reference RPCs use `data_*` prefix for all operations (including create/delete) as an exception to the standard naming pattern. This maintains consistency within the file reference system.
+
+**Read Operations:**
+- `data_file_reference_get` - Get a file reference by ID
+- `data_file_reference_list` - List file references for a record
+- `data_file_reference_url_get` - Get public URL for a file
+- `data_file_reference_signed_url_get` - Get signed URL path for private files
+- `data_file_reference_by_category_list` - List files by category
+- `data_file_reference_count_get` - Get count of file references for a record
+
+**Write Operations (exception to naming standard):**
+- `data_file_reference_create` - Create a file reference (uses `data_*` prefix for consistency within file reference system)
+- `data_file_reference_delete` - Delete a file reference (uses `data_*` prefix for consistency within file reference system)
+
+### RBAC System
+
+Documented in [RBAC API Reference](../rbac/api-reference.md):
+
+**Permission Checking:**
+- `rbac_permission_check` - Check if user has a specific permission
+- `rbac_permissions_get` - Get all permissions for current user in a scope
+- `rbac_access_validate` - Validate user access to a resource
+- `rbac_page_access_check` - Check page-level access permissions
+
+**Role Management:**
+- `rbac_role_grant` - Grant a role to a user
+- `rbac_role_revoke` - Revoke a role from a user
+- `rbac_roles_list` - List available roles
+- `rbac_role_validate` - Validate role configuration
+
+**Session & Audit:**
+- `rbac_session_track` - Track user session activity
+- `rbac_audit_log` - Log RBAC-related actions
+
+**Data Access (RBAC-protected):**
+- `data_user_organisations_get` - Get all organisations for a user
+- `data_user_organisation_roles_get` - Get user roles in organisations
+- `data_user_events_get` - Get events accessible to a user
+- `data_cake_meals_get` - Get cake meals for an event (application-specific, RBAC-protected)
+
+**Additional RBAC Functions:**
+- `rbac_check_permission_simplified` - Simplified permission check (event-scoped)
+- `rbac_check_distribution_or_page_permission` - Check distribution or page permissions
+
+**Utility:**
+- `util_app_resolve` - Resolve app ID from app name
+- `util_get_cake_app_id` - Get CAKE app ID (application-specific utility)
+- `debug_auth_context` - Debug authentication context (development only)
+- `handle_new_user` - Handle new user registration (triggered automatically)
+
+### Event System
+
+- `data_user_events_get` - Get events accessible to a user (replaces deprecated `get_pace_user_events`)
+- `get_public_event_by_code` - Get public event by code (public access, exception to naming pattern)
+- `data_event_list` - List events (if implemented)
+- `app_event_create` - Create an event (if implemented)
+
+**Note**: `get_public_event_by_code` is a legacy function that doesn't follow the standard naming pattern. It's maintained for backward compatibility with public pages.
+
+## Application-Specific RPCs
+
+Each application may define its own RPC functions following the naming convention. Common patterns include:
+
+### Cake Application Example
+
+```sql
+-- Read operations
+data_cake_dishes_list(p_organisation_id UUID, p_event_id UUID)
+data_cake_diner_get(p_diner_id UUID, p_organisation_id UUID)
+data_cake_diners_list(p_organisation_id UUID, p_event_id UUID)
+
+-- Write operations
+app_cake_dish_create(p_organisation_id UUID, p_event_id UUID, p_data JSONB)
+app_cake_dish_update(p_dish_id UUID, p_organisation_id UUID, p_data JSONB)
+app_cake_dish_delete(p_dish_id UUID, p_organisation_id UUID)
+
+-- Bulk operations
+app_cake_dish_create_bulk(p_organisation_id UUID, p_event_id UUID, p_data JSONB[])
+```
+
+## Finding RPC Functions
+
+### In Supabase Dashboard
+
+1. Navigate to **Database** → **Functions**
+2. Filter by prefix (`data_`, `app_`, `rbac_`, or `util_`)
+3. Review function signatures and documentation
+
+### In Migration Files
+
+RPC functions are defined in Supabase migration files:
+
+```bash
+supabase/migrations/YYYYMMDDHHMMSS_description.sql
+```
+
+Search for `CREATE OR REPLACE FUNCTION` statements:
+
+```sql
+CREATE OR REPLACE FUNCTION data_file_reference_list(
+  p_table_name TEXT,
+  p_record_id TEXT,
+  p_organisation_id UUID
+)
+RETURNS TABLE(...)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+BEGIN
+  -- Function implementation
+END;
+$$;
+```
+
+## Security Considerations
+
+### Organisation Context
+
+All RPC functions validate organisation context:
+
+```sql
+-- Functions check organisation membership
+IF NOT EXISTS (
+  SELECT 1 FROM user_organisation_memberships
+  WHERE user_id = auth.uid()
+  AND organisation_id = p_organisation_id
+) THEN
+  RAISE EXCEPTION 'Access denied';
+END IF;
+```
+
+### RLS Enforcement
+
+RPC functions run with `SECURITY DEFINER` but still respect RLS policies:
+
+- Functions validate organisation membership
+- Functions check user permissions
+- Direct table access is protected by RLS
+
+### Error Handling
+
+RPC functions return user-safe errors:
+
+```sql
+BEGIN
+  -- Validation
+  IF p_organisation_id IS NULL THEN
+    RAISE EXCEPTION 'Organisation ID is required';
+  END IF;
+  
+  -- Business logic
+  -- ...
+  
+EXCEPTION
+  WHEN OTHERS THEN
+    RAISE EXCEPTION 'Operation failed: %', SQLERRM;
+END;
+```
+
+## Best Practices
+
+### 1. Always Pass Organisation Context
+
+```typescript
+// ✅ Good
+const { data, error } = await supabase.rpc('data_file_reference_list', {
+  p_table_name: 'pace_person',
+  p_record_id: personId,
+  p_organisation_id: currentOrganisationId // Always include
+});
+
+if (error) {
+  console.error('Failed to list file references:', error);
+  return;
+}
+
+// Use data
+const fileReferences = data;
+
+// ❌ Bad - Missing organisation context
+const { data, error } = await supabase.rpc('data_file_reference_list', {
+  p_table_name: 'pace_person',
+  p_record_id: personId
+  // Missing p_organisation_id - will fail RLS validation
+});
+```
+
+### 2. Handle Errors Properly
+
+```typescript
+const { data, error } = await supabase.rpc('app_cake_dish_create', {
+  p_organisation_id: orgId,
+  p_event_id: eventId,
+  p_data: dishData
+});
+
+if (error) {
+  // Check error code
+  if (error.code === 'PGRST301' || error.message?.includes('Access denied')) {
+    // Handle permission error
+    toast.error('You do not have permission to create dishes');
+  } else {
+    // Handle other errors
+    toast.error('Failed to create dish');
+  }
+  return;
+}
+
+// Use data
+const newDish = data;
+```
+
+### 3. Use TypeScript Types
+
+```typescript
+// Define RPC result types
+type FileReferenceListResult = {
+  id: string;
+  table_name: string;
+  record_id: string;
+  file_path: string;
+  // ... other fields
+}[];
+
+const { data, error } = await supabase.rpc<FileReferenceListResult>(
+  'data_file_reference_list',
+  {
+    p_table_name: 'pace_person',
+    p_record_id: personId,
+    p_organisation_id: orgId
+  }
+);
+
+if (error) {
+  console.error('RPC error:', error);
+  return;
+}
+
+// TypeScript now knows the shape of data
+if (data) {
+  data.forEach(ref => {
+    console.log(ref.file_path); // Type-safe access
+  });
+}
+```
+
+### 4. Prefer RPCs Over Direct Queries
+
+```typescript
+// ✅ Good - Use RPC function with proper error handling
+const { data, error } = await supabase.rpc('data_file_reference_list', {
+  p_table_name: 'pace_person',
+  p_record_id: personId,
+  p_organisation_id: orgId
+});
+
+if (error) {
+  console.error('Failed to list file references:', error);
+  return;
+}
+
+// Use data - RPC enforces RLS and organisation context
+const fileReferences = data;
+
+// ❌ Bad - Direct query bypasses RLS validation and organisation checks
+const { data, error } = await supabase
+  .from('file_references')
+  .select('*')
+  .eq('table_name', 'pace_person')
+  .eq('record_id', personId);
+  // Missing organisation context validation
+  // May expose data from other organisations
+```
+
+## Deprecated RPCs
+
+See [Deprecated APIs](./deprecated.md) for RPC functions that are deprecated and their migration paths.
+
+## Related Documentation
+
+- [API & RPC Standard](../standards/02-api-and-rpc-standard.md) - Complete RPC standards
+- [File Reference System](../implementation-guides/file-reference-system.md) - File reference RPCs
+- [RBAC API Reference](../rbac/api-reference.md) - RBAC RPC functions
+- [Database Schema Requirements](../architecture/database-schema-requirements.md) - Required RPC functions
+