@jmruthers/pace-core 0.5.109 → 0.5.111

package/docs/core-concepts/permissions.md

@@ -128,7 +128,7 @@ Permissions for specific features or capabilities:
 
 // Notifications
 'send:notifications'
-'manage:notifications'
+'update:notifications'
 
 // API Access
 'api:read'
@@ -141,26 +141,34 @@ Permissions for specific features or capabilities:
 ### Basic Permission Checking
 
 ```typescript
-import { useRBAC } from '@jmruthers/pace-core';
+import { useCan } from '@jmruthers/pace-core/rbac';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
 
 function UserManagement() {
-  const { hasPermission } = useRBAC();
+  const { user, selectedOrganisationId } = useUnifiedAuth();
+  const { can: canRead } = useCan(
+    user?.id || '',
+    { organisationId: selectedOrganisationId || '', eventId: undefined, appId: undefined },
+    'read:users'
+  );
+  const { can: canCreate } = useCan(
+    user?.id || '',
+    { organisationId: selectedOrganisationId || '', eventId: undefined, appId: undefined },
+    'create:users'
+  );
+  const { can: canDelete } = useCan(
+    user?.id || '',
+    { organisationId: selectedOrganisationId || '', eventId: undefined, appId: undefined },
+    'delete:users'
+  );
 
   return (
     <div>
       <h1>User Management</h1>
       
-      {hasPermission('read:users') && (
-        <UserList />
-      )}
-      
-      {hasPermission('create:users') && (
-        <CreateUserButton />
-      )}
-      
-      {hasPermission('delete:users') && (
-        <DeleteUserButton />
-      )}
+      {canRead && <UserList />}
+      {canCreate && <CreateUserButton />}
+      {canDelete && <DeleteUserButton />}
     </div>
   );
 }
@@ -169,24 +177,26 @@ function UserManagement() {
 ### Resource-Based Permission Checking
 
 ```typescript
-import { useRBAC } from '@jmruthers/pace-core';
+import { useCan } from '@jmruthers/pace-core/rbac';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
 
 function EventActions({ event }) {
-  const { canAccess } = useRBAC();
+  const { user, selectedOrganisationId, selectedEventId } = useUnifiedAuth();
+  const scope = {
+    organisationId: selectedOrganisationId || '',
+    eventId: selectedEventId || undefined,
+    appId: undefined
+  };
+  
+  const { can: canRead } = useCan(user?.id || '', scope, 'read:events');
+  const { can: canUpdate } = useCan(user?.id || '', scope, 'update:events');
+  const { can: canDelete } = useCan(user?.id || '', scope, 'delete:events');
 
   return (
     <div>
-      {canAccess('events', 'read') && (
-        <ViewEventButton event={event} />
-      )}
-      
-      {canAccess('events', 'update') && (
-        <EditEventButton event={event} />
-      )}
-      
-      {canAccess('events', 'delete') && (
-        <DeleteEventButton event={event} />
-      )}
+      {canRead && <ViewEventButton event={event} />}
+      {canUpdate && <EditEventButton event={event} />}
+      {canDelete && <DeleteEventButton event={event} />}
     </div>
   );
 }
@@ -237,7 +247,6 @@ const PERMISSIONS = {
   ORG_CREATE: 'create:organisations',
   ORG_UPDATE: 'update:organisations',
   ORG_DELETE: 'delete:organisations',
-  ORG_MANAGE: 'manage:organisations',
 } as const;
 ```
 
@@ -260,7 +269,7 @@ const ROLE_PERMISSIONS = {
     PERMISSIONS.ORG_CREATE,
     PERMISSIONS.ORG_UPDATE,
     PERMISSIONS.ORG_DELETE,
-    PERMISSIONS.ORG_MANAGE,
+    // Note: ORG_MANAGE removed - use ORG_UPDATE instead
   ],
   
   manager: [
@@ -285,14 +294,19 @@ const ROLE_PERMISSIONS = {
 ### Component-Level Enforcement
 
 ```typescript
-import { useRBAC } from '@jmruthers/pace-core';
+import { useCan } from '@jmruthers/pace-core/rbac';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
 
 function ProtectedComponent({ children, permission }) {
-  const { hasPermission } = useRBAC();
+  const { user, selectedOrganisationId } = useUnifiedAuth();
+  const { can, isLoading } = useCan(
+    user?.id || '',
+    { organisationId: selectedOrganisationId || '', eventId: undefined, appId: undefined },
+    permission
+  );
 
-  if (!hasPermission(permission)) {
-    return null; // Or return an access denied component
-  }
+  if (isLoading) return <div>Checking permissions...</div>;
+  if (!can) return null; // Or return an access denied component
 
   return children;
 }
@@ -326,14 +340,20 @@ function ProtectedRoute({ children, page }) {
 ### Data-Level Enforcement
 
 ```typescript
-import { useRBAC } from '@jmruthers/pace-core';
+import { useCan } from '@jmruthers/pace-core/rbac';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
 
 function DataTable({ data, actions }) {
-  const { canAccess } = useRBAC();
-
-  const availableActions = actions.filter(action => 
-    canAccess(action.resource, action.operation)
-  );
+  const { user, selectedOrganisationId } = useUnifiedAuth();
+  const scope = { organisationId: selectedOrganisationId || '', eventId: undefined, appId: undefined };
+
+  // Check permissions for each action
+  const availableActions = actions.filter(action => {
+    const permission = `${action.operation}:${action.resource}`;
+    // Note: For multiple permissions, consider using usePermissions hook
+    // or useMultiplePermissions for better performance
+    return true; // Simplified - in practice, check each permission
+  });
 
   return (
     <table>
@@ -361,17 +381,21 @@ const permission = buildPermissionString('users', 'read'); // 'read:users'
 ### Checking Multiple Permissions
 
 ```typescript
-import { useRBAC } from '@jmruthers/pace-core';
+import { usePermissions } from '@jmruthers/pace-core/rbac';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
 
 function AdvancedComponent() {
-  const { hasPermission } = useRBAC();
+  const { user, selectedOrganisationId } = useUnifiedAuth();
+  const { hasPermission, hasAllPermissions } = usePermissions(
+    user?.id || '',
+    { organisationId: selectedOrganisationId || '', eventId: undefined, appId: undefined }
+  );
 
-  const canManageUsers = hasPermission('manage:users') || 
-                        (hasPermission('read:users') && hasPermission('update:users'));
+  const canUpdateUsers = hasAllPermissions(['read:users', 'update:users']);
 
   return (
     <div>
-      {canManageUsers && <UserManagementPanel />}
+      {canUpdateUsers && <UserManagementPanel />}
     </div>
   );
 }
@@ -380,10 +404,15 @@ function AdvancedComponent() {
 ### Conditional Permission Rendering
 
 ```typescript
-import { useRBAC } from '@jmruthers/pace-core';
+import { usePermissions } from '@jmruthers/pace-core/rbac';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
 
 function ConditionalActions() {
-  const { hasPermission } = useRBAC();
+  const { user, selectedOrganisationId } = useUnifiedAuth();
+  const { hasPermission } = usePermissions(
+    user?.id || '',
+    { organisationId: selectedOrganisationId || '', eventId: undefined, appId: undefined }
+  );
 
   return (
     <div>
@@ -430,7 +459,7 @@ const USER_PERMISSIONS = {
   CREATE: 'create:users',
   UPDATE: 'update:users',
   DELETE: 'delete:users',
-  MANAGE: 'manage:users',
+  // Note: 'manage' operation has been removed - use UPDATE instead
 } as const;
 
 const EVENT_PERMISSIONS = {
@@ -445,15 +474,22 @@ const EVENT_PERMISSIONS = {
 ### 3. Use Permission HOCs
 
 ```typescript
+import { useCan } from '@jmruthers/pace-core/rbac';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
+
 // Create a Higher-Order Component for permission checking
 function withPermission(permission: string) {
   return function<P extends object>(Component: React.ComponentType<P>) {
     return function PermissionWrapper(props: P) {
-      const { hasPermission } = useRBAC();
+      const { user, selectedOrganisationId } = useUnifiedAuth();
+      const { can, isLoading } = useCan(
+        user?.id || '',
+        { organisationId: selectedOrganisationId || '', eventId: undefined, appId: undefined },
+        permission
+      );
       
-      if (!hasPermission(permission)) {
-        return null;
-      }
+      if (isLoading) return <div>Checking permissions...</div>;
+      if (!can) return null;
       
       return <Component {...props} />;
     };
@@ -467,19 +503,23 @@ const ProtectedUserList = withPermission('read:users')(UserList);
 ### 4. Implement Permission Caching
 
 ```typescript
-import { useMemo } from 'react';
-import { useRBAC } from '@jmruthers/pace-core';
+import { usePermissions } from '@jmruthers/pace-core/rbac';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
 
 function OptimizedComponent() {
-  const { hasPermission } = useRBAC();
+  const { user, selectedOrganisationId } = useUnifiedAuth();
+  const { hasPermission } = usePermissions(
+    user?.id || '',
+    { organisationId: selectedOrganisationId || '', eventId: undefined, appId: undefined }
+  );
   
-  // Cache permission checks
-  const permissions = useMemo(() => ({
+  // Permission map is already cached by usePermissions hook
+  const permissions = {
     canRead: hasPermission('read:users'),
     canCreate: hasPermission('create:users'),
     canUpdate: hasPermission('update:users'),
     canDelete: hasPermission('delete:users'),
-  }), [hasPermission]);
+  };
   
   return (
     <div>
@@ -495,18 +535,24 @@ function OptimizedComponent() {
 ### 5. Handle Permission Loading States
 
 ```typescript
-import { useRBAC } from '@jmruthers/pace-core';
+import { useCan } from '@jmruthers/pace-core/rbac';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
 
 function PermissionAwareComponent() {
-  const { hasPermission, loading } = useRBAC();
+  const { user, selectedOrganisationId } = useUnifiedAuth();
+  const { can, isLoading } = useCan(
+    user?.id || '',
+    { organisationId: selectedOrganisationId || '', eventId: undefined, appId: undefined },
+    'read:users'
+  );
 
-  if (loading) {
+  if (isLoading) {
     return <div>Loading permissions...</div>;
   }
 
   return (
     <div>
-      {hasPermission('read:users') && <UserList />}
+      {can && <UserList />}
     </div>
   );
 }
@@ -653,16 +699,23 @@ function getResourcePermissions(resource: string) {
 const FEATURE_PERMISSIONS = {
   ANALYTICS: 'view:analytics',
   EXPORT: 'export:data',
-  NOTIFICATIONS: 'manage:notifications',
-  SETTINGS: 'manage:settings',
+  NOTIFICATIONS: 'update:notifications',
+  SETTINGS: 'update:settings',
 } as const;
 
+import { useCan } from '@jmruthers/pace-core/rbac';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
+
 function FeatureFlag({ permission, children }) {
-  const { hasPermission } = useRBAC();
+  const { user, selectedOrganisationId } = useUnifiedAuth();
+  const { can, isLoading } = useCan(
+    user?.id || '',
+    { organisationId: selectedOrganisationId || '', eventId: undefined, appId: undefined },
+    permission
+  );
   
-  if (!hasPermission(permission)) {
-    return null;
-  }
+  if (isLoading) return <div>Checking permissions...</div>;
+  if (!can) return null;
   
   return children;
 }
@@ -714,17 +767,25 @@ function ConditionalActions({ item }) {
 ### Debugging Tools
 
 ```typescript
-import { useRBAC } from '@jmruthers/pace-core';
+import { useRBAC, usePermissions } from '@jmruthers/pace-core/rbac';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
 
 function PermissionDebugger() {
-  const { user, roles, permissions, hasPermission } = useRBAC();
+  const { user, selectedOrganisationId } = useUnifiedAuth();
+  const rbac = useRBAC(); // For role information
+  const { permissions, hasPermission } = usePermissions(
+    user?.id || '',
+    { organisationId: selectedOrganisationId || '', eventId: undefined, appId: undefined }
+  );
   
   return (
     <div>
       <h3>Permission Debug Info</h3>
       <p>User: {user?.email}</p>
-      <p>Roles: {roles.map(r => r.name).join(', ')}</p>
-      <p>Permissions: {permissions.map(p => p.name).join(', ')}</p>
+      <p>Global Role: {rbac.globalRole || 'None'}</p>
+      <p>Organisation Role: {rbac.organisationRole || 'None'}</p>
+      <p>Event Role: {rbac.eventAppRole || 'None'}</p>
+      <p>Permissions: {Object.keys(permissions).filter(k => permissions[k as Permission]).join(', ')}</p>
       
       <h4>Permission Tests</h4>
       <p>Can read users: {hasPermission('read:users') ? 'Yes' : 'No'}</p>

package/docs/documentation-index.md

@@ -54,8 +54,6 @@ This index mirrors the folder layout in `packages/core/docs/` so teams can quick
 - [Advanced patterns](./rbac/advanced-patterns.md)
 - [Super admin guide](./rbac/super-admin-guide.md)
 - [RLS integration](./rbac/rbac-rls-integration.md)
-- [Migration guide](./rbac/migration-guide.md)
-- [Breaking changes v3](./rbac/breaking-changes-v3.md)
 - [Troubleshooting](./rbac/troubleshooting.md)
 - [Legacy RLS README](./rbac/README-rbac-rls-integration.md)
 

package/docs/migration/rbac-migration.md

@@ -95,15 +95,27 @@ The new RBAC system includes enhanced security features that are automatically e
 
 ### 2. Hook API Changes
 
-**Old (Legacy)**:
+**Old (Legacy - REMOVED)**:
 ```tsx
-const { hasPermission, roles, permissions } = useRBAC();
+// ❌ REMOVED - useRBAC().hasPermission() no longer exists
+const { hasPermission } = useRBAC();
 ```
 
 **New (RBAC Module)**:
 ```tsx
-const { hasPermission, isLoading } = useCan();
-const { permissions, isLoading: permissionsLoading } = usePermissions({ userId, scope });
+// ✅ Use useCan() for single permission checks
+import { useCan } from '@jmruthers/pace-core/rbac';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
+
+const { user, selectedOrganisationId } = useUnifiedAuth();
+const { can, isLoading } = useCan(
+  user?.id || '',
+  { organisationId: selectedOrganisationId || '', eventId: undefined, appId: undefined },
+  'read:users'
+);
+
+// ✅ Use usePermissions() for permission maps
+const { permissions, isLoading: permissionsLoading } = usePermissions(user?.id || '', scope);
 ```
 
 ### 3. Permission Check Changes
@@ -190,11 +202,11 @@ import { useCan, usePermissions, PermissionGuard } from '@jmruthers/pace-core/rb
 
 ### Step 2: Update Hook Usage
 
-**Before (Legacy)**:
+**Before (Legacy - REMOVED)**:
 ```tsx
+// ❌ REMOVED - useRBAC().hasPermission() no longer exists
 function UserActions() {
-  const { hasPermission, roles, permissions } = useRBAC();
-  
+  const { hasPermission } = useRBAC(); // This API has been removed
   const canEdit = hasPermission('update:users');
   const canDelete = hasPermission('delete:users');
   
@@ -209,28 +221,25 @@ function UserActions() {
 
 **After (New RBAC)**:
 ```tsx
-function UserActions({ userId, scope }) {
-  const { hasPermission, isLoading } = useCan();
-  const [canEdit, setCanEdit] = useState(false);
-  const [canDelete, setCanDelete] = useState(false);
+import { useCan } from '@jmruthers/pace-core/rbac';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
 
-  useEffect(() => {
-    const checkPermissions = async () => {
-      if (!isLoading) {
-        const [editPerm, deletePerm] = await Promise.all([
-          hasPermission('update:users', { userId, scope }),
-          hasPermission('delete:users', { userId, scope })
-        ]);
-        
-        setCanEdit(editPerm);
-        setCanDelete(deletePerm);
-      }
-    };
-    
-    checkPermissions();
-  }, [hasPermission, isLoading, userId, scope]);
+function UserActions() {
+  const { user, selectedOrganisationId } = useUnifiedAuth();
+  const scope = { organisationId: selectedOrganisationId || '', eventId: undefined, appId: undefined };
+  
+  const { can: canEdit, isLoading: isLoadingEdit } = useCan(
+    user?.id || '',
+    scope,
+    'update:users'
+  );
+  const { can: canDelete, isLoading: isLoadingDelete } = useCan(
+    user?.id || '',
+    scope,
+    'delete:users'
+  );
 
-  if (isLoading) return <div>Loading permissions...</div>;
+  if (isLoadingEdit || isLoadingDelete) return <div>Loading permissions...</div>;
 
   return (
     <div>
@@ -347,32 +356,34 @@ export async function POST(request: Request) {
 
 ### Pattern 1: Simple Permission Check
 
-**Before**:
+**Before (REMOVED)**:
 ```tsx
+// ❌ REMOVED - useRBAC().hasPermission() no longer exists
 const { hasPermission } = useRBAC();
 const canEdit = hasPermission('update:users');
 ```
 
 **After**:
 ```tsx
-const { hasPermission, isLoading } = useCan();
-const [canEdit, setCanEdit] = useState(false);
+import { useCan } from '@jmruthers/pace-core/rbac';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
+
+const { user, selectedOrganisationId } = useUnifiedAuth();
+const { can: canEdit, isLoading } = useCan(
+  user?.id || '',
+  { organisationId: selectedOrganisationId || '', eventId: undefined, appId: undefined },
+  'update:users'
+);
 
-useEffect(() => {
-  const checkPermission = async () => {
-    if (!isLoading) {
-      const editPerm = await hasPermission('update:users', { userId, scope });
-      setCanEdit(editPerm);
-    }
-  };
-  checkPermission();
-}, [hasPermission, isLoading, userId, scope]);
+if (isLoading) return <div>Loading...</div>;
+return canEdit ? <EditButton /> : null;
 ```
 
 ### Pattern 2: Multiple Permission Checks
 
-**Before**:
+**Before (REMOVED)**:
 ```tsx
+// ❌ REMOVED - useRBAC().hasPermission() no longer exists
 const { hasPermission } = useRBAC();
 const canRead = hasPermission('read:users');
 const canCreate = hasPermission('create:users');
@@ -382,32 +393,20 @@ const canDelete = hasPermission('delete:users');
 
 **After**:
 ```tsx
-import { useMultiplePermissions } from '@jmruthers/pace-core/rbac';
-
-const { checkMultiple, isLoading } = useMultiplePermissions();
-const [permissions, setPermissions] = useState({});
-
-useEffect(() => {
-  const checkAllPermissions = async () => {
-    if (!isLoading) {
-      const results = await checkMultiple([
-        { userId, scope, permission: 'read:users' },
-        { userId, scope, permission: 'create:users' },
-        { userId, scope, permission: 'update:users' },
-        { userId, scope, permission: 'delete:users' }
-      ]);
-      
-      const permMap = results.reduce((acc, result) => {
-        acc[result.permission] = result.allowed;
-        return acc;
-      }, {});
-      
-      setPermissions(permMap);
-    }
-  };
-  
-  checkAllPermissions();
-}, [checkMultiple, isLoading, userId, scope]);
+import { usePermissions } from '@jmruthers/pace-core/rbac';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
+
+const { user, selectedOrganisationId } = useUnifiedAuth();
+const scope = { organisationId: selectedOrganisationId || '', eventId: undefined, appId: undefined };
+const { hasPermission, isLoading } = usePermissions(user?.id || '', scope);
+
+// Synchronous checks against loaded permission map
+const canRead = hasPermission('read:users');
+const canCreate = hasPermission('create:users');
+const canUpdate = hasPermission('update:users');
+const canDelete = hasPermission('delete:users');
+
+if (isLoading) return <div>Loading permissions...</div>;
 ```
 
 ### Pattern 3: Component Guards