feat: enhance usePermissions hook with error handling and loading states

Author: bra-i-am

docs/how_tos/permissions.md

@@ -52,30 +52,43 @@ Permission keys are spread at the top level — no nested `.permissions` object.
 
 ```typescript
 import { usePermissions } from '@openedx/frontend-base';
-import { getConfig } from '@edx/frontend-platform';
 
 // featureEnabled is required — always pass the resolved waffle flag boolean:
 const { enableAuthz } = useWaffleFlags(resourceId);
-const { isLoading, isAuthzEnabled, canViewGrading, canEditGrading } = usePermissions(
+const { isLoading, isError, isAuthzEnabled, canViewGrading, canEditGrading } = usePermissions(
   {
     canViewGrading: { action: 'courses.view_grading_settings', scope: resourceId },
     canEditGrading: { action: 'courses.edit_grading_settings', scope: resourceId },
   },
   enableAuthz ?? false,
 );
 
-// Override the backend URL (e.g. MFEs using @edx/frontend-platform):
-const { isLoading, canViewGrading } = usePermissions(
+if (isLoading) { return <LoadingSpinner />; }
+if (isError) { return <ErrorAlert />; }
+if (!canViewGrading) { return <PermissionDeniedAlert />; }
+```
+
+When `featureEnabled` is `false`: no API call is made and all keys return `true`,
+preserving the pre-authz behavior during rollout.
+
+To override the backend URL (e.g. MFEs using `@edx/frontend-platform`), pass `apiBaseUrl`
+in the options argument:
+
+```typescript
+import { usePermissions } from '@openedx/frontend-base';
+import { getConfig } from '@edx/frontend-platform';
+
+const { enableAuthz } = useWaffleFlags(courseId);
+const { isLoading, isError, canViewGrading } = usePermissions(
   { canViewGrading: { action: 'courses.view_grading_settings', scope: courseId } },
   enableAuthz ?? false,
   { apiBaseUrl: getConfig().LMS_BASE_URL },
 );
-
-if (!canViewGrading) { return <PermissionDeniedAlert />; }
 ```
 
-When `featureEnabled` is `false`: no API call is made and all keys return `true`,
-preserving the pre-authz behavior during rollout.
+> **Service unavailability:** if the authz API call fails, `isError` is `true` and all
+> permission keys resolve to `false`. Always check `isLoading` and `isError` before
+> rendering gated UI to avoid incorrectly denying access during transient failures.
 
 ---
 

runtime/authz/hooks.test.tsx

@@ -45,6 +45,7 @@ describe('usePermissions', () => {
     expect(result.current.canView).toBe(true);
     expect(result.current.canEdit).toBe(false);
     expect(result.current.isAuthzEnabled).toBe(true);
+    expect(result.current.isError).toBe(false);
   });
 
   it('returns all keys as true and makes no API call when featureEnabled is false', () => {
@@ -60,6 +61,7 @@ describe('usePermissions', () => {
     expect(result.current.canView).toBe(true);
     expect(result.current.canEdit).toBe(true);
     expect(result.current.isLoading).toBe(false);
+    expect(result.current.isError).toBe(false);
     expect(result.current.isAuthzEnabled).toBe(false);
   });
 
@@ -97,6 +99,39 @@ describe('usePermissions', () => {
     expect('permissions' in result.current).toBe(false);
   });
 
+  it('returns undefined permission keys and isLoading=true while the API call is in flight', async () => {
+    (getAuthenticatedHttpClient as jest.Mock).mockReturnValue({
+      post: jest.fn(() => new Promise(() => {})), // never resolves
+    });
+
+    const { result } = renderHook(
+      () => usePermissions(QUERY, true, { apiBaseUrl: BASE_URL }),
+      { wrapper: createWrapper() },
+    );
+
+    expect(result.current.isLoading).toBe(true);
+    expect(result.current.canView).toBeUndefined();
+    expect(result.current.canEdit).toBeUndefined();
+  });
+
+  it('sets isError=true and defaults all keys to false when the API call fails', async () => {
+    jest.spyOn(console, 'error').mockImplementation(() => {});
+    (getAuthenticatedHttpClient as jest.Mock).mockReturnValue({
+      post: jest.fn().mockRejectedValue(new Error('network error')),
+    });
+
+    const { result } = renderHook(
+      () => usePermissions(QUERY, true, { apiBaseUrl: BASE_URL }),
+      { wrapper: createWrapper() },
+    );
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.isError).toBe(true);
+    expect(result.current.canView).toBe(false);
+    expect(result.current.canEdit).toBe(false);
+    jest.restoreAllMocks();
+  });
+
   it('scopes cache by apiBaseUrl — different base URLs produce distinct query keys', () => {
     const keyA = permissionsQueryKeys.validate(QUERY, 'http://lms-a.example.com');
     const keyB = permissionsQueryKeys.validate(QUERY, 'http://lms-b.example.com');

runtime/authz/hooks.ts

@@ -3,6 +3,14 @@ import { getSiteConfig } from '../config';
 import type { PermissionValidationQuery, PermissionValidationAnswer } from './types';
 import { validatePermissions } from './api';
 
+/**
+ * TanStack Query cache key factory for permission queries.
+ * Use `validate` to scope cache reads and invalidations to a specific
+ * query + backend combination.
+ *
+ * @example
+ * queryClient.invalidateQueries({ queryKey: permissionsQueryKeys.validate(myQuery) });
+ */
 export const permissionsQueryKeys = {
   all: ['authz'] as const,
   validate: (query: PermissionValidationQuery, apiBaseUrl: string = getSiteConfig().lmsBaseUrl) =>
@@ -22,14 +30,20 @@ export interface UsePermissionsOptions {
 
 /**
  * Intersection return type: metadata fields plus every permission key spread at the top level.
- * Consumers destructure permission keys directly, no nested from `permissions.*` object.
+ * Consumers destructure permission keys directly — no nested `.permissions` object.
  *
  * @example
- * const { isLoading, canViewGradingSettings, canEditGradingSettings } =
- *   usePermissions(query, featureEnabled);
+ * const { enableAuthz } = useWaffleFlags(courseId);
+ * const { isLoading, isError, canViewGrading, canEditGrading } = usePermissions(
+ *   { canViewGrading: { action: 'courses.view_grading_settings', scope: courseId },
+ *     canEditGrading: { action: 'courses.edit_grading_settings', scope: courseId } },
+ *   enableAuthz ?? false,
+ *   { apiBaseUrl: getConfig().LMS_BASE_URL },
+ * );
  */
 export type UsePermissionsResult<Query extends PermissionValidationQuery> = {
   isLoading: boolean,
+  isError: boolean,
   isAuthzEnabled: boolean,
 } & PermissionValidationAnswer<Query>;
 
@@ -41,7 +55,7 @@ export type UsePermissionsResult<Query extends PermissionValidationQuery> = {
  * When featureEnabled is true: hits the authz API; returns actual server values.
  *
  * The caller is responsible for reading its own waffle flag and passing the result
- * as featureEnabled — waffle flag differ per MFE
+ * as featureEnabled — waffle flag names differ per MFE
  *
  * @param query          - Key/value map of permission check descriptors.
  * @param featureEnabled - Pass the result of your waffle flag check here.
@@ -63,7 +77,7 @@ export const usePermissions = <Query extends PermissionValidationQuery>(
 ): UsePermissionsResult<Query> => {
   const { retry = false, apiBaseUrl = getSiteConfig().lmsBaseUrl } = options;
 
-  const { isLoading, data } = useQuery<PermissionValidationAnswer<Query>, Error>({
+  const { isLoading, isError, data } = useQuery<PermissionValidationAnswer<Query>, Error>({
     queryKey: permissionsQueryKeys.validate(query, apiBaseUrl),
     queryFn: featureEnabled ? () => validatePermissions(apiBaseUrl, query) : skipToken,
     retry,
@@ -81,6 +95,7 @@ export const usePermissions = <Query extends PermissionValidationQuery>(
 
   return {
     isLoading: featureEnabled ? isLoading : false,
+    isError: featureEnabled ? isError : false,
     isAuthzEnabled: featureEnabled,
     ...permissionResults,
   } as UsePermissionsResult<Query>;