@jmruthers/pace-core 0.6.1 → 0.6.3

package/src/rbac/hooks/permissions/usePermissions.ts

@@ -0,0 +1,253 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { Permission, PermissionMap, Scope, UUID } from '../../types';
+import { getPermissionMap } from '../../api';
+import { getRBACLogger } from '../../config';
+
+/**
+ * Hook to get user's permissions in a scope
+ *
+ * @param userId - User ID
+ * @param organisationId - Organisation ID
+ * @param eventId - Event ID (optional)
+ * @param appId - Application ID (optional)
+ * @returns Permission state and methods
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { permissions, isLoading, error } = usePermissions(
+ *     userId,
+ *     organisationId,
+ *     eventId,
+ *     appId
+ *   );
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       {permissions['read:users'] && <UserList />}
+ *       {permissions['create:users'] && <CreateUserButton />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function usePermissions(
+  userId: UUID,
+  organisationId: string | undefined,
+  eventId: string | undefined,
+  appId: string | undefined
+) {
+  const [permissions, setPermissions] = useState<PermissionMap>({} as PermissionMap);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+  const [fetchTrigger, setFetchTrigger] = useState(0);
+  const isFetchingRef = useRef(false);
+  const logger = getRBACLogger();
+
+  // Track previous values to detect changes imperatively
+  const prevValuesRef = useRef({ userId, organisationId, eventId, appId });
+
+  // Normalize organisationId to empty string if undefined
+  const orgId = organisationId || '';
+
+  // Add timeout for missing organisation context (3 seconds)
+  // OPTIMIZATION: Skip timeout if userId is null/undefined (indicates pre-filtered mode)
+  useEffect(() => {
+    // If userId is null/undefined, skip the timeout - this indicates items are pre-filtered
+    // and we don't need to wait for organisation context
+    if (!userId) {
+      return; // Skip timeout when userId is null (pre-filtered mode)
+    }
+
+    if (!orgId || orgId === null || (typeof orgId === 'string' && orgId.trim() === '')) {
+      const timeoutId = setTimeout(() => {
+        setError(new Error('Organisation context is required for permission checks'));
+        setIsLoading(false);
+      }, 3000); // 3 seconds - typical permission check is < 1 second
+
+      return () => clearTimeout(timeoutId);
+    }
+    // Clear error if organisation context becomes available
+    if (error?.message === 'Organisation context is required for permission checks') {
+      setError(null);
+    }
+  }, [userId, organisationId, error, orgId]);
+
+  // CRITICAL: Detect parameter changes and trigger fetch
+  // Moved to useEffect to prevent render-time state updates that could cause render loops
+  useEffect(() => {
+    const paramsChanged =
+      prevValuesRef.current.userId !== userId ||
+      prevValuesRef.current.organisationId !== organisationId ||
+      prevValuesRef.current.eventId !== eventId ||
+      prevValuesRef.current.appId !== appId;
+
+    if (paramsChanged) {
+      // Only log significant changes (appId changes are most important)
+      if (prevValuesRef.current.appId !== appId) {
+        // AppId changed - triggering fetch
+      }
+      prevValuesRef.current = { userId, organisationId, eventId, appId };
+      // Increment counter to force fetch useEffect to run
+      setFetchTrigger(prev => prev + 1);
+    }
+  }, [userId, organisationId, eventId, appId, logger]);
+
+  useEffect(() => {
+    const fetchPermissions = async () => {
+      // Prevent multiple simultaneous fetches
+      if (isFetchingRef.current) {
+        return;
+      }
+
+      if (!userId) {
+        setPermissions({} as PermissionMap);
+        setIsLoading(false);
+        return;
+      }
+
+      // Don't fetch permissions if scope is invalid (e.g., organisationId is null/empty)
+      // Wait for organisation context to resolve
+      // IMPORTANT: Don't clear existing permissions here - keep them until we have new ones
+      // OPTIMIZATION: If userId is null/undefined, immediately set loading to false
+      // This indicates pre-filtered mode where we don't need to wait for organisation context
+      if (!userId) {
+        setPermissions({} as PermissionMap);
+        setIsLoading(false);
+        return;
+      }
+
+      if (!orgId || orgId === null || (typeof orgId === 'string' && orgId.trim() === '')) {
+        // Keep existing permissions, just mark as loading
+        setIsLoading(true);
+        setError(null);
+        return;
+      }
+
+      try {
+        isFetchingRef.current = true;
+        setIsLoading(true);
+        setError(null);
+
+        // Build scope object for API call
+        const scope: Scope = {
+          organisationId: orgId,
+          eventId: eventId,
+          appId: appId
+        };
+
+        // Fetch new permissions - don't clear old ones until we have new ones
+        const permissionMap = await getPermissionMap({ userId, scope });
+
+        // Only log if there's a significant change or error
+        const permissionCount = Object.keys(permissionMap).length;
+        if (permissionCount === 0 && Object.keys(permissions).length > 0) {
+          logger.warn('[usePermissions] Permissions fetched but returned empty map', {
+            scope: { organisationId: orgId, eventId, appId }
+          });
+        }
+
+        // Only update permissions if fetch was successful
+        setPermissions(permissionMap);
+      } catch (err) {
+        // On error, keep existing permissions but set error state
+        // This prevents the UI from losing all items when there's a transient error
+        logger.error('[usePermissions] Failed to fetch permissions:', err);
+        setError(err instanceof Error ? err : new Error('Failed to fetch permissions'));
+        // Don't clear permissions on error - keep what we had
+      } finally {
+        setIsLoading(false);
+        isFetchingRef.current = false;
+      }
+    };
+
+    fetchPermissions();
+  }, [fetchTrigger, userId, organisationId, eventId, appId]);
+
+  const hasPermission = useCallback((permission: Permission): boolean => {
+    if (permissions['*']) {
+      return true;
+    }
+    return permissions[permission] === true;
+  }, [permissions]);
+
+  const hasAnyPermission = useCallback((permissionList: Permission[]): boolean => {
+    if (permissions['*']) {
+      return true;
+    }
+    return permissionList.some(p => permissions[p] === true);
+  }, [permissions]);
+
+  const hasAllPermissions = useCallback((permissionList: Permission[]): boolean => {
+    if (permissions['*']) {
+      return true;
+    }
+    return permissionList.every(p => permissions[p] === true);
+  }, [permissions]);
+
+  const refetch = useCallback(async () => {
+    // Prevent multiple simultaneous fetches
+    if (isFetchingRef.current) {
+      return;
+    }
+
+    if (!userId) {
+      setPermissions({} as PermissionMap);
+      setIsLoading(false);
+      return;
+    }
+
+    // Don't fetch permissions if scope is invalid (e.g., organisationId is null/empty)
+    // IMPORTANT: Don't clear existing permissions - keep them until we have new ones
+    if (!orgId || orgId === null || (typeof orgId === 'string' && orgId.trim() === '')) {
+      // Keep existing permissions, just mark as loading
+      setIsLoading(true);
+      setError(null);
+      return;
+    }
+
+    try {
+      isFetchingRef.current = true;
+      setIsLoading(true);
+      setError(null);
+
+      // Build scope object for API call
+      const scope: Scope = {
+        organisationId: orgId,
+        eventId: eventId,
+        appId: appId
+      };
+
+      // Fetch new permissions - don't clear old ones until we have new ones
+      const permissionMap = await getPermissionMap({ userId, scope });
+
+      // Only update permissions if fetch was successful
+      setPermissions(permissionMap);
+    } catch (err) {
+      // On error, keep existing permissions but set error state
+      // This prevents the UI from losing all items when there's a transient error
+      const logger = getRBACLogger();
+      logger.error('Failed to refetch permissions:', err);
+      setError(err instanceof Error ? err : new Error('Failed to fetch permissions'));
+      // Don't clear permissions on error - keep what we had
+    } finally {
+      setIsLoading(false);
+      isFetchingRef.current = false;
+    }
+  }, [userId, organisationId, eventId, appId]);
+
+  // Memoize the return object to prevent unnecessary re-renders
+  return useMemo(() => ({
+    permissions,
+    isLoading,
+    error,
+    hasPermission,
+    hasAnyPermission,
+    hasAllPermissions,
+    refetch
+  }), [permissions, isLoading, error, hasPermission, hasAnyPermission, hasAllPermissions, refetch]);
+}