@jmruthers/pace-core 0.5.76 → 0.5.78

package/docs/troubleshooting/authentication-issues.md

@@ -1,334 +0,0 @@
-# Troubleshooting Authentication Issues
-
-> **🔐 Auth Problems?** | [← Back to Troubleshooting](../README.md) | [Troubleshooting Overview](./README.md)
-
-Quick fixes and solutions for common authentication issues with PACE Core.
-
-## 🚨 Most Common Issues
-
-### Login Not Working
-
-**Symptoms:**
-- Login button does nothing
-- "Invalid credentials" error
-- Redirect not happening after login
-
-**Immediate Fix:**
-```tsx
-// ✅ Ensure proper provider hierarchy
-import { UnifiedAuthProvider } from '@jmruthers/pace-core';
-import { supabase } from './lib/supabase';
-
-function App() {
-  return (
-    <UnifiedAuthProvider
-      supabaseClient={supabase}
-      appName="my-app"
-      idleTimeoutMs={30 * 60 * 1000}
-      warnBeforeMs={5 * 60 * 1000}
-      onIdleLogout={() => window.location.href = '/login'}
-    >
-      <YourApp />
-    </UnifiedAuthProvider>
-  );
-}
-```
-
-**Checklist:**
-- [ ] Supabase URL and key are correct
-- [ ] Provider hierarchy correct (Auth > Org > Event)
-- [ ] User credentials are valid in Supabase
-- [ ] Network connectivity working
-- [ ] Browser not blocking cookies
-
-### Session Not Persisting
-
-**Symptoms:**
-- User logged out on page refresh
-- Session cleared on browser restart
-- Need to login repeatedly
-
-**Fix:**
-```tsx
-// Check Supabase session configuration
-const supabase = createClient(url, key, {
-  auth: {
-    persistSession: true,
-    storage: window.localStorage,
-    autoRefreshToken: true,
-    detectSessionInUrl: true
-  }
-});
-
-// Verify session exists
-useEffect(() => {
-  supabase.auth.getSession().then(({ data: { session } }) => {
-    console.log('Current session:', session);
-  });
-}, []);
-```
-
-### User State Not Updating
-
-**Symptoms:**
-- Login succeeds but user state is null
-- `useUnifiedAuth()` returns undefined
-- Components don't react to auth changes
-
-**Fix:**
-```tsx
-// ✅ Ensure provider is set up correctly
-function App() {
-  return (
-    <UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
-      <AuthTest />
-    </UnifiedAuthProvider>
-  );
-}
-
-function AuthTest() {
-  const { user, loading, error } = useUnifiedAuth();
-  
-  if (loading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
-  if (!user) return <div>Not logged in</div>;
-  
-  return <div>Welcome {user.email}</div>;
-}
-```
-
-## 🔧 Detailed Solutions
-
-### Wrong Supabase Configuration
-
-**Problem:** Using service role key instead of anon key
-
-```tsx
-// ❌ WRONG - Service role key
-const supabase = createClient(url, SERVICE_ROLE_KEY);
-
-// ✅ CORRECT - Anonymous key
-const supabase = createClient(url, ANON_KEY);
-
-// Check key format
-console.log('Key starts with:', ANON_KEY.substring(0, 30));
-// Should be: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
-```
-
-### Provider Hierarchy Issues
-
-**Problem:** Providers not in correct order
-
-```tsx
-// ❌ WRONG ORDER
-<EventProvider>
-  <OrganisationProvider>
-    <UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
-      <App />
-    </UnifiedAuthProvider>
-  </OrganisationProvider>
-</EventProvider>
-
-// ✅ CORRECT ORDER
-<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
-  <OrganisationProvider>
-    <EventProvider>
-      <App />
-    </EventProvider>
-  </OrganisationProvider>
-</UnifiedAuthProvider>
-```
-
-### Missing Inactivity Timeout Props
-
-**Problem:** TypeScript error in v0.5.65+
-
-```tsx
-// ❌ OLD API (broken in v0.5.65+)
-<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
-  <App />
-</UnifiedAuthProvider>
-
-// ✅ NEW API (required)
-<UnifiedAuthProvider
-  supabaseClient={supabase}
-  appName="my-app"
-  idleTimeoutMs={30 * 60 * 1000}    // Required
-  warnBeforeMs={5 * 60 * 1000}      // Required
-  onIdleLogout={() => navigate('/login')} // Required
->
-  <App />
-</UnifiedAuthProvider>
-```
-
-### Permission Errors After Login
-
-**Problem:** Logged in but permissions don't work
-
-**Debug Steps:**
-```tsx
-// Check user roles
-const { data: userRoles } = await supabase
-  .from('rbac_user_roles')
-  .select('*, rbac_roles(*)')
-  .eq('user_id', user.id);
-
-console.log('User roles:', userRoles);
-
-// Check organisation membership
-const { data: memberships } = await supabase
-  .from('organisation_memberships')
-  .select('*')
-  .eq('user_id', user.id)
-  .eq('status', 'active');
-
-console.log('Organisation memberships:', memberships);
-```
-
-## 🧪 Debugging Techniques
-
-### Enable Debug Logging
-
-```tsx
-<UnifiedAuthProvider
-  supabaseClient={supabase}
-  appName="my-app"
-  debug={true} // Enable debug mode
-  idleTimeoutMs={30 * 60 * 1000}
-  warnBeforeMs={5 * 60 * 1000}
-  onIdleLogout={() => window.location.href = '/login'}
->
-  <App />
-</UnifiedAuthProvider>
-```
-
-### Check Auth State
-
-```tsx
-function AuthDebugger() {
-  const { user, loading, error, session } = useUnifiedAuth();
-  
-  useEffect(() => {
-    console.log('Auth state:', {
-      user: user?.id,
-      email: user?.email,
-      loading,
-      error: error?.message,
-      hasSession: !!session
-    });
-  }, [user, loading, error, session]);
-  
-  return null;
-}
-
-// Add to your app
-<AuthDebugger />
-```
-
-### Monitor Auth Events
-
-```tsx
-import { useEffect } from 'react';
-import { supabase } from './lib/supabase';
-
-useEffect(() => {
-  const {
-    data: { subscription },
-  } = supabase.auth.onAuthStateChange((event, session) => {
-    console.log('Auth event:', event, session?.user?.id);
-    
-    if (event === 'SIGNED_IN') {
-      console.log('User signed in:', session?.user);
-    }
-    if (event === 'SIGNED_OUT') {
-      console.log('User signed out');
-    }
-    if (event === 'TOKEN_REFRESHED') {
-      console.log('Token refreshed');
-    }
-  });
-
-  return () => subscription.unsubscribe();
-}, []);
-```
-
-## 🔍 Common Error Messages
-
-### "Missing supabaseClient prop"
-
-**Problem:** `UnifiedAuthProvider` not receiving supabase client
-
-**Fix:**
-```tsx
-// ✅ Ensure you're passing the client
-import { createClient } from '@supabase/supabase-js';
-import { UnifiedAuthProvider } from '@jmruthers/pace-core';
-
-const supabase = createClient(url, key);
-
-<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
-  <App />
-</UnifiedAuthProvider>
-```
-
-### "Invalid credentials"
-
-**Problem:** Wrong email/password or user not found
-
-**Solutions:**
-1. Check user exists in Supabase Auth
-2. Verify email/password are correct
-3. Check email confirmation required
-4. Verify user is not disabled
-
-```tsx
-// Check user exists
-const { data, error } = await supabase.auth.signInWithPassword({
-  email: 'user@example.com',
-  password: 'password'
-});
-console.log('Login result:', { data, error });
-```
-
-### "Missing timeout props" (v0.5.65+)
-
-**Problem:** Required props not provided
-
-**Fix:**
-```tsx
-// Add all required props
-<UnifiedAuthProvider
-  supabaseClient={supabase}
-  appName="my-app"
-  idleTimeoutMs={30 * 60 * 1000}    // 30 minutes
-  warnBeforeMs={5 * 60 * 1000}      // 5 minutes warning
-  onIdleLogout={() => window.location.href = '/login'}
->
-  <App />
-</UnifiedAuthProvider>
-```
-
-## 📚 Related Documentation
-
-- [Authentication Guide](../core-concepts/authentication.md) - Complete auth docs
-- [Installation Guide](../getting-started/installation-guide.md) - Setup
-- [Common Issues](./common-issues.md) - General troubleshooting
-- [RBAC System](../rbac/README.md) - Permissions documentation
-
-## 🆘 Still Not Working?
-
-If you've tried everything:
-
-1. **Check browser console** for detailed error messages
-2. **Verify Supabase dashboard** - User exists and is active
-3. **Test with test credentials** from Supabase
-4. **File an issue** with:
-   - PACE Core version
-   - Error messages
-   - Steps to reproduce
-   - Code snippets
-
----
-
-**Last Updated:** 2025-01-XX | **Version:** v0.5.65+
-