@jmruthers/pace-core 0.5.141 → 0.5.142

package/src/rbac/docs/event-based-apps.md

@@ -1,285 +0,0 @@
-# Event-Based Apps with RBAC
-
-This guide explains how to use the RBAC system for event-based applications where the organization context is automatically derived from the event context.
-
-## Overview
-
-Event-based apps are applications that operate within the context of a specific event. Since events inherently belong to an organization, these apps don't need explicit organization context - it is automatically resolved from the event by the RBAC components.
-
-## Key Concepts
-
-### Automatic Organization Resolution
-The RBAC components automatically resolve the organization from the event context when needed. You only need to provide the `eventId` (and optionally `appId`), and the system handles the rest.
-
-```typescript
-// The components automatically resolve organisationId from eventId
-const scope: Scope = {
-  eventId: 'event-123',
-  appId: 'app-456' // optional
-  // organisationId is automatically resolved
-};
-```
-
-### Permission Hierarchy
-For event-based apps, the permission hierarchy is:
-1. **Page-level permissions** (most specific)
-2. **Event-app permissions** (event + app specific)
-3. **Organization permissions** (automatically resolved from event)
-4. **Global permissions** (least specific)
-
-## Components
-
-The same RBAC components work for both organization-based and event-based apps. They automatically detect the context and resolve the organization when needed.
-
-### PermissionEnforcer
-Use this component for general permission enforcement in event-based apps:
-
-```tsx
-import { PermissionEnforcer } from '@jmruthers/pace-core/rbac';
-
-function EventDashboard() {
-  return (
-    <PermissionEnforcer
-      permissions={['read:events', 'update:participants']}
-      operation="dashboard"
-    >
-      <div>Event Dashboard Content</div>
-    </PermissionEnforcer>
-  );
-}
-```
-
-### PagePermissionGuard
-Use this component for page-level permission enforcement:
-
-```tsx
-import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
-
-function EventSettingsPage() {
-  return (
-    <PagePermissionGuard
-      pageName="settings"
-      operation="read"
-    >
-      <div>Event Settings</div>
-    </PagePermissionGuard>
-  );
-}
-```
-
-### NavigationGuard
-Use this component for navigation-level permission enforcement:
-
-```tsx
-import { NavigationGuard } from '@jmruthers/pace-core/rbac';
-
-const navigationItems = [
-  {
-    id: 'dashboard',
-    name: 'Dashboard',
-    path: '/event/dashboard',
-    permissions: ['read:events']
-  },
-  {
-    id: 'settings',
-    name: 'Settings',
-    path: '/event/settings',
-    permissions: ['update:events']
-  }
-];
-
-function EventNavigation() {
-  return (
-    <nav>
-      {navigationItems.map(item => (
-        <NavigationGuard
-          key={item.id}
-          navigationItem={item}
-        >
-          <Link to={item.path}>{item.name}</Link>
-        </NavigationGuard>
-      ))}
-    </nav>
-  );
-}
-```
-
-## Hooks
-
-### useCan with Event Context
-You can use the standard `useCan` hook with event-based scopes:
-
-```tsx
-import { useCan } from '@jmruthers/pace-core/rbac';
-
-function EventComponent() {
-  const { selectedEventId } = useUnifiedAuth();
-  
-  const { can: canManageEvents } = useCan(
-    userId,
-    { eventId: selectedEventId },
-    'update:events'
-  );
-
-  return (
-    <div>
-      {canManageEvents && (
-        <button>Manage Event</button>
-      )}
-    </div>
-  );
-}
-```
-
-## Setup
-
-### 1. Event Context Provider
-Ensure your app has event context available:
-
-```tsx
-import { UnifiedAuthProvider } from '@jmruthers/pace-core';
-
-function App() {
-  return (
-    <UnifiedAuthProvider>
-      {/* Your event-based app components */}
-    </UnifiedAuthProvider>
-  );
-}
-```
-
-### 2. Event Selection
-Make sure the event is selected in the auth context:
-
-```tsx
-import { useUnifiedAuth } from '@jmruthers/pace-core';
-
-function EventSelector() {
-  const { setSelectedEventId } = useUnifiedAuth();
-  
-  const handleEventSelect = (eventId: string) => {
-    setSelectedEventId(eventId);
-  };
-
-  return (
-    <select onChange={(e) => handleEventSelect(e.target.value)}>
-      <option value="event-1">Event 1</option>
-      <option value="event-2">Event 2</option>
-    </select>
-  );
-}
-```
-
-## Permission Types
-
-### Event-App Permissions
-These permissions are specific to an event and app combination:
-
-```typescript
-const EVENT_APP_PERMISSIONS = {
-  // Event management
-  MANAGE_EVENT: 'update:event',
-  READ_EVENT: 'read:event',
-  UPDATE_EVENT: 'update:event',
-  
-  // Participant management
-  MANAGE_PARTICIPANTS: 'update:participants',
-  READ_PARTICIPANTS: 'read:participants',
-  CREATE_PARTICIPANTS: 'create:participants',
-  UPDATE_PARTICIPANTS: 'update:participants',
-  DELETE_PARTICIPANTS: 'delete:participants',
-  
-  // App-specific permissions
-  MANAGE_APP: 'update:app',
-  READ_APP: 'read:app',
-  UPDATE_APP: 'update:app',
-};
-```
-
-### Page Permissions
-Page permissions are specific to individual pages within an event app:
-
-```typescript
-const PAGE_PERMISSIONS = {
-  DASHBOARD_READ: 'read:page.dashboard',
-  DASHBOARD_WRITE: 'write:page.dashboard',
-  SETTINGS_READ: 'read:page.settings',
-  SETTINGS_WRITE: 'write:page.settings',
-  PARTICIPANTS_READ: 'read:page.participants',
-  PARTICIPANTS_WRITE: 'write:page.participants',
-};
-```
-
-## Best Practices
-
-### 1. Use Event-Based Components
-Always use the event-based components (`EventPermissionEnforcer`, `EventPagePermissionGuard`, `EventNavigationGuard`) instead of the organization-based ones for event apps.
-
-### 2. Provide Explicit Scopes
-When possible, provide explicit scopes to avoid context resolution overhead:
-
-```tsx
-<EventPermissionEnforcer
-  scope={{ eventId: 'event-123', appId: 'app-456' }}
-  permissions={['read:events']}
->
-  <div>Content</div>
-</EventPermissionEnforcer>
-```
-
-### 3. Handle Loading States
-Event-based components automatically handle loading states while resolving the organization from the event:
-
-```tsx
-<EventPermissionEnforcer
-  permissions={['read:events']}
-  loading={<div>Loading permissions...</div>}
->
-  <div>Content</div>
-</EventPermissionEnforcer>
-```
-
-### 4. Error Handling
-Handle cases where the organization cannot be resolved from the event:
-
-```tsx
-<EventPermissionEnforcer
-  permissions={['read:events']}
-  onDenied={(permission, reason) => {
-    console.error(`Permission denied: ${permission}, reason: ${reason}`);
-  }}
->
-  <div>Content</div>
-</EventPermissionEnforcer>
-```
-
-## Migration from Organization-Based Apps
-
-If you're migrating from organization-based apps to event-based apps:
-
-1. Replace `PermissionEnforcer` with `EventPermissionEnforcer`
-2. Replace `PagePermissionGuard` with `EventPagePermissionGuard`
-3. Replace `NavigationGuard` with `EventNavigationGuard`
-4. Remove explicit organization context from your components
-5. Ensure event context is available in your app
-
-## Troubleshooting
-
-### Common Issues
-
-1. **"Event context is required" error**: Make sure `selectedEventId` is set in the auth context
-2. **"Could not resolve organization from event context" error**: Verify the event exists and has a valid `organisation_id`
-3. **Permission checks failing**: Ensure the user has the appropriate event-app roles assigned
-
-### Debug Mode
-
-Enable debug mode to see detailed permission resolution:
-
-```typescript
-import { createRBACConfig } from '@jmruthers/pace-core/rbac';
-
-const config = createRBACConfig({
-  debug: true,
-  logLevel: 'debug'
-});
-```