@jmruthers/pace-core 0.5.68 → 0.5.69

package/docs/architecture/services.md

@@ -0,0 +1,374 @@
+# Service Architecture Documentation
+
+## Overview
+
+The pace-core library now uses a service-based architecture that follows SOLID principles and provides better testability, maintainability, and separation of concerns. This architecture separates business logic into pure TypeScript service classes and provides React integration through providers and hooks.
+
+## Architecture Design
+
+### Service Layer (Pure TypeScript Classes)
+
+The service layer contains pure TypeScript classes that handle business logic without any React dependencies:
+
+- **AuthService**: Authentication operations (sign in, sign out, session management)
+- **RBACService**: Role and permission management
+- **OrganisationService**: Organisation management and selection
+- **EventService**: Event management and selection
+- **InactivityService**: User inactivity tracking
+
+### Provider Layer (React Context)
+
+Each service has its own React provider that:
+- Creates and manages service instances
+- Provides services to React components via context
+- Handles service lifecycle (initialization, cleanup)
+
+### Hook Layer (React Integration)
+
+Each service has corresponding hooks that:
+- Access services from context
+- Subscribe to service state changes
+- Trigger React re-renders when state changes
+
+## Service Interfaces
+
+All services implement clear interfaces that define their contracts:
+
+```typescript
+// Example: AuthService interface
+export interface IAuthService {
+  // State getters
+  getUser(): User | null;
+  getSession(): Session | null;
+  isAuthenticated(): boolean;
+  isLoading(): boolean;
+  getError(): AuthError | null;
+
+  // Methods
+  signIn(email: string, password?: string): Promise<AuthResult>;
+  signOut(): Promise<AuthResult>;
+  // ... other methods
+
+  // Lifecycle
+  initialize(): Promise<void>;
+  cleanup(): void;
+}
+```
+
+## Base Service Class
+
+All services extend the `BaseService` class which provides:
+
+- **Observable Pattern**: Services can notify subscribers of state changes
+- **Lifecycle Management**: Standardized initialization and cleanup
+- **State Management**: Consistent state update patterns
+
+```typescript
+export abstract class BaseService {
+  // Subscribe to state changes
+  subscribe(callback: StateChangeCallback): () => void;
+  
+  // Notify subscribers of state changes
+  protected notify(): void;
+  
+  // Lifecycle methods
+  async initialize(): Promise<void>;
+  cleanup(): void;
+}
+```
+
+## Usage Examples
+
+### Basic Setup
+
+```tsx
+import { NewUnifiedAuthProvider } from '@core/providers/services/NewUnifiedAuthProvider';
+
+function App() {
+  return (
+    <NewUnifiedAuthProvider
+      supabaseClient={supabase}
+      appName="MY_APP"
+      idleTimeoutMs={30 * 60 * 1000} // 30 minutes
+      warnBeforeMs={60 * 1000} // 60 seconds
+      onIdleLogout={() => window.location.href = '/login'}
+    >
+      <YourAppContent />
+    </NewUnifiedAuthProvider>
+  );
+}
+```
+
+### Using Services in Components
+
+```tsx
+import { useNewUnifiedAuth } from '@core/providers/services/NewUnifiedAuthProvider';
+
+function MyComponent() {
+  const auth = useNewUnifiedAuth();
+  
+  return (
+    <div>
+      <h1>Welcome, {auth.user?.email}</h1>
+      <p>Your role: {auth.roles.join(', ')}</p>
+      <p>Organisation: {auth.selectedOrganisation?.display_name}</p>
+      <p>Events: {auth.events.length}</p>
+    </div>
+  );
+}
+```
+
+### Using Individual Service Hooks
+
+```tsx
+import { useAuth } from '@core/hooks/services/useAuth';
+import { usePermissions } from '@core/hooks/services/usePermissions';
+import { useCurrentOrganisation } from '@core/hooks/services/useCurrentOrganisation';
+import { useCurrentEvent } from '@core/hooks/services/useCurrentEvent';
+
+function MyComponent() {
+  const auth = useAuth();
+  const permissions = usePermissions();
+  const organisation = useCurrentOrganisation();
+  const events = useCurrentEvent();
+  
+  return (
+    <div>
+      {auth.isAuthenticated && (
+        <div>
+          <h1>{organisation.selectedOrganisation?.display_name}</h1>
+          {permissions.hasPermission('events:read') && (
+            <EventList events={events.events} />
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+## Testing
+
+### Unit Tests for Services
+
+Services are pure TypeScript classes, making them easy to unit test:
+
+```typescript
+describe('AuthService', () => {
+  let mockSupabase: SupabaseClient;
+  let authService: AuthService;
+  
+  beforeEach(() => {
+    mockSupabase = createMockSupabaseClient();
+    authService = new AuthService(mockSupabase);
+  });
+  
+  it('signs in user successfully', async () => {
+    mockSupabase.auth.signInWithPassword.mockResolvedValue({
+      data: { user: mockUser, session: mockSession },
+      error: null
+    });
+    
+    const result = await authService.signIn('test@example.com', 'password');
+    
+    expect(result.user).toEqual(mockUser);
+    expect(authService.getUser()).toEqual(mockUser);
+    expect(authService.isAuthenticated()).toBe(true);
+  });
+});
+```
+
+### Integration Tests for Providers
+
+Providers can be tested with React Testing Library:
+
+```typescript
+describe('AuthServiceProvider Integration', () => {
+  it('provides auth service to components', async () => {
+    render(
+      <AuthServiceProvider supabaseClient={mockSupabase}>
+        <TestComponent />
+      </AuthServiceProvider>
+    );
+    
+    await waitFor(() => {
+      expect(screen.getByTestId('user-id')).toHaveTextContent('test-user-id');
+    });
+  });
+});
+```
+
+## Benefits
+
+### 1. SOLID Principles
+
+- **Single Responsibility**: Each service has one clear purpose
+- **Open/Closed**: Easy to extend without modifying existing code
+- **Liskov Substitution**: Services implement clear interfaces
+- **Interface Segregation**: Components depend only on what they need
+- **Dependency Inversion**: Services depend on interfaces, not concrete implementations
+
+### 2. Testability
+
+- Services are pure TypeScript classes (easy unit testing)
+- No React dependencies in business logic
+- Easy to mock services in tests
+- Clear separation between unit and integration tests
+
+### 3. Maintainability
+
+- Clear service boundaries
+- Easy to understand and reason about
+- Easy to add new services
+- Easy to modify existing services
+
+### 4. Performance
+
+- Services instantiated once and reused
+- Efficient state updates via observable pattern
+- No unnecessary re-renders
+
+### 5. Type Safety
+
+- Full TypeScript support
+- Clear interfaces for all services
+- Type-safe method calls
+
+## Migration Guide
+
+### From Old Architecture
+
+The new architecture provides backward compatibility through the `NewUnifiedAuthProvider` which maintains the same API as the old `UnifiedAuthProvider`:
+
+```tsx
+// Old way
+import { UnifiedAuthProvider } from '@core/providers';
+
+// New way
+import { NewUnifiedAuthProvider } from '@core/providers/services/NewUnifiedAuthProvider';
+
+// Same API, better architecture
+<NewUnifiedAuthProvider
+  supabaseClient={supabase}
+  appName="MY_APP"
+  idleTimeoutMs={30 * 60 * 1000}
+  warnBeforeMs={60 * 1000}
+  onIdleLogout={() => window.location.href = '/login'}
+>
+  <YourAppContent />
+</NewUnifiedAuthProvider>
+```
+
+### Gradual Migration
+
+You can migrate gradually by:
+
+1. **Start with new apps**: Use `NewUnifiedAuthProvider` for new applications
+2. **Migrate existing apps**: Replace `UnifiedAuthProvider` with `NewUnifiedAuthProvider`
+3. **Use individual services**: Gradually move to individual service hooks for better performance
+4. **Remove old providers**: Once migration is complete, remove old provider imports
+
+## File Structure
+
+```
+packages/core/src/
+├── services/
+│   ├── interfaces/
+│   │   ├── IAuthService.ts
+│   │   ├── IRBACService.ts
+│   │   ├── IOrganisationService.ts
+│   │   ├── IEventService.ts
+│   │   └── IInactivityService.ts
+│   ├── base/
+│   │   └── BaseService.ts
+│   ├── AuthService.ts
+│   ├── RBACService.ts
+│   ├── OrganisationService.ts
+│   ├── EventService.ts
+│   ├── InactivityService.ts
+│   └── __tests__/
+│       ├── AuthService.test.ts
+│       └── RBACService.test.ts
+├── providers/
+│   └── services/
+│       ├── AuthServiceProvider.tsx
+│       ├── RBACServiceProvider.tsx
+│       ├── OrganisationServiceProvider.tsx
+│       ├── EventServiceProvider.tsx
+│       ├── InactivityServiceProvider.tsx
+│       ├── NewUnifiedAuthProvider.tsx
+│       └── __tests__/
+│           ├── AuthServiceProvider.integration.test.tsx
+│           └── NewUnifiedAuthProvider.integration.test.tsx
+└── hooks/
+    └── services/
+        ├── useAuthService.ts
+        ├── useRBACService.ts
+        ├── useOrganisationService.ts
+        ├── useEventService.ts
+        ├── useInactivityService.ts
+        ├── useAuth.ts
+        ├── usePermissions.ts
+        ├── useCurrentOrganisation.ts
+        └── useCurrentEvent.ts
+```
+
+## Best Practices
+
+### 1. Service Usage
+
+- Use individual service hooks for better performance
+- Use convenience hooks for common patterns
+- Use the unified provider for backward compatibility
+
+### 2. Testing
+
+- Write unit tests for services
+- Write integration tests for providers
+- Mock services in component tests
+
+### 3. Error Handling
+
+- Services handle their own errors
+- Providers expose error states
+- Components handle error display
+
+### 4. State Management
+
+- Services manage their own state
+- Use the observable pattern for updates
+- Avoid direct state manipulation
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Service not initialized**: Ensure the service is properly initialized in the provider
+2. **State not updating**: Check that components are subscribed to service changes
+3. **Memory leaks**: Ensure services are properly cleaned up on unmount
+4. **Test failures**: Mock services properly in tests
+
+### Debug Tips
+
+1. **Check service state**: Use service getters to inspect current state
+2. **Verify subscriptions**: Ensure components are subscribed to service changes
+3. **Check provider setup**: Verify all required providers are present
+4. **Inspect errors**: Check service error states for debugging information
+
+## Future Enhancements
+
+### Planned Features
+
+1. **Service Middleware**: Add middleware support for cross-cutting concerns
+2. **Service Composition**: Better service composition patterns
+3. **Performance Monitoring**: Add performance monitoring to services
+4. **Service Registry**: Centralized service registration and discovery
+
+### Contributing
+
+When contributing to the service architecture:
+
+1. **Follow interfaces**: Always implement service interfaces
+2. **Write tests**: Include unit and integration tests
+3. **Document changes**: Update documentation for new features
+4. **Maintain compatibility**: Ensure backward compatibility when possible

package/docs/best-practices/README.md

@@ -268,7 +268,7 @@ const UserCard: React.FC<{ user: User }> = ({ user }) => {
 };
 ```
 
-### Code Organization
+### Code Organisation
 
 **✅ Do:**
 - Use consistent file naming

package/docs/best-practices/testing.md

@@ -34,7 +34,7 @@ Testing in `@jmruthers/pace-core` covers multiple layers:
 // - Critical user journeys
 ```
 
-### 2. Test Organization
+### 2. Test Organisation
 
 ```typescript
 // File structure

package/docs/breaking-changes.md

@@ -0,0 +1,182 @@
+# PACE Core Breaking Changes
+
+> **📢 Important**: This document tracks all breaking changes in PACE Core.  
+> **Check this file** before upgrading to a new major version.
+
+## Recent Breaking Changes
+
+### v0.5.65+ - Mandatory Inactivity Timeouts
+
+**Status**: ⚠️ **BREAKING CHANGE**  
+**Date**: January 2025  
+**Impact**: High - Affects all apps using `UnifiedAuthProvider`
+
+#### What Changed
+
+The `UnifiedAuthProvider` now requires mandatory inactivity timeout configuration. These props were previously optional but are now required for security and TypeScript compliance.
+
+#### Before (Old Code)
+
+```tsx
+// ❌ This will now cause TypeScript errors
+<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+  <App />
+</UnifiedAuthProvider>
+```
+
+#### After (New Code)
+
+```tsx
+// ✅ Required configuration
+<UnifiedAuthProvider 
+  supabaseClient={supabase} 
+  appName="my-app"
+  idleTimeoutMs={30 * 60 * 1000}  // Required: 30 minutes
+  warnBeforeMs={5 * 60 * 1000}    // Required: 5 minutes warning
+  onIdleLogout={() => window.location.href = '/login'}  // Required
+>
+  <App />
+</UnifiedAuthProvider>
+```
+
+#### Required Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `idleTimeoutMs` | `number` | ✅ Yes | Idle timeout in milliseconds |
+| `warnBeforeMs` | `number` | ✅ Yes | Warning before logout in milliseconds |
+| `onIdleLogout` | `() => void` | ✅ Yes | Callback when user is logged out |
+
+#### Migration Steps
+
+1. **Identify all UnifiedAuthProvider instances** in your codebase
+2. **Add the three required props** to each instance
+3. **Choose appropriate timeout values** for your application
+4. **Test the inactivity warning and logout flow**
+
+#### Migration Guide
+
+See the complete [Migration Guide](./migration-guides/unified-auth-provider-mandatory-timeouts.md) for detailed instructions.
+
+#### Why This Change
+
+This breaking change was made for security reasons:
+- Ensures all apps have automatic logout functionality
+- Prevents security vulnerabilities from idle sessions
+- Provides consistent user experience across all apps
+- Improves overall security posture
+
+---
+
+### v2.0.0 - Service Architecture Changes
+
+**Status**: ⚠️ **BREAKING CHANGE**  
+**Date**: December 2024  
+**Impact**: Medium - Affects apps using service architecture
+
+#### What Changed
+
+The library now uses a service-based architecture with pure TypeScript service classes and React integration through providers and hooks.
+
+#### Key Changes
+
+- ✅ **New Service Layer**: Pure TypeScript classes for business logic
+- ✅ **Provider Layer**: React context integration for services
+- ✅ **Hook Layer**: Reactive hooks for component integration
+- ✅ **Backward Compatible**: `UnifiedAuthProvider` maintained for compatibility
+
+#### Migration
+
+Migration is optional. Existing code continues to work. To adopt new architecture:
+
+```tsx
+// Old way (still works)
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+
+// New way (optional)
+import { NewUnifiedAuthProvider } from '@core/providers/services/NewUnifiedAuthProvider';
+```
+
+See [Service Architecture Guide](./architecture/services.md) for details.
+
+---
+
+## Version History
+
+### v0.5.65+
+- ⚠️ Mandatory inactivity timeouts in UnifiedAuthProvider
+- ⚠️ Breaking TypeScript interface changes
+
+### v2.0.0
+- ⚠️ Service architecture introduced (backward compatible)
+- ⚠️ New provider patterns available
+
+### v0.4.17
+- ⚠️ Source path fixes for Tailwind scanning
+- Migration guide: [v0.4.17 Source Path Fix](./migration/v0.4.17-source-path-fix.md)
+
+### v0.4.16
+- ⚠️ CSS-first approach for Tailwind v4
+- Migration guide: [CSS-First Migration](./migration/v0.4.16-css-first-approach.md)
+
+### v0.4.15
+- ⚠️ Tailwind content scanning requirements
+- Migration guide: [Tailwind Scanning](./migration/v0.4.15-tailwind-scanning.md)
+
+## Checking for Breaking Changes
+
+### Before Upgrading
+
+1. **Check this file** for breaking changes in your target version
+2. **Review migration guides** for each breaking change
+3. **Test in development environment** before production
+4. **Update TypeScript** to catch type errors early
+
+### Finding Your Current Version
+
+```bash
+npm list @jmruthers/pace-core
+```
+
+Or check your `package.json`:
+```json
+{
+  "dependencies": {
+    "@jmruthers/pace-core": "^0.5.65"
+  }
+}
+```
+
+## Migration Resources
+
+- [Unified Migration Guide](./migration/MIGRATION_GUIDE.md)
+- [Service Architecture Migration](./migration/service-architecture.md)
+- [RBAC Migration](./migration/rbac-migration.md)
+- [All Migration Guides](./migration/)
+
+## Getting Help
+
+If you encounter issues during migration:
+
+1. Check the specific migration guide for your breaking change
+2. Review [Troubleshooting](./troubleshooting/common-issues.md)
+3. See [Common Issues](./troubleshooting/common-issues.md)
+4. File an issue with version and error details
+
+## Staying Updated
+
+To stay informed about breaking changes:
+
+- 📢 **Check this file** before each upgrade
+- 📢 **Review release notes** on GitHub
+- 📢 **Subscribe to notifications** for major versions
+- 📢 **Follow migration guides** step-by-step
+
+---
+
+**Remember**: Always test breaking changes in a development environment before deploying to production.
+
+**Last Updated**: January 2025  
+**Current Stable Version**: v0.5.65+  
+**Next Major Version**: v1.0.0 (TBD)
+