@epcare/esm-report-builder 0.1.1-pre.76 → 0.1.1-pre.78

package/src/hooks/use-report-builder-privileges.test.tsx

@@ -0,0 +1,98 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+
+import { useSession } from '@openmrs/esm-framework';
+import { useReportBuilderPrivileges } from './use-report-builder-privileges';
+import { RB } from '../constants/privileges';
+
+jest.mock('@openmrs/esm-framework', () => ({
+    useSession: jest.fn(),
+}));
+
+const mockUseSession = useSession as unknown as jest.Mock;
+
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+const priv = (name: string) => ({ uuid: name, name, display: name });
+
+function renderHook<T>(hook: () => T): { current: T | undefined; rerender: () => void; unmount: () => void } {
+    const container = document.createElement('div');
+    const root = createRoot(container);
+    let current: T | undefined;
+    const Probe = () => {
+        current = hook();
+        return null;
+    };
+    const render = () => act(() => {
+        root.render(React.createElement(Probe));
+    });
+    render();
+    return {
+        get current() {
+            return current;
+        },
+        rerender: render,
+        unmount: () => act(() => root.unmount()),
+    };
+}
+
+function sessionWith(privileges: string[], roles: string[] = [], authenticated = true) {
+    return {
+        authenticated,
+        user: {
+            uuid: 'u-1',
+            display: 'User',
+            privileges: privileges.map(priv),
+            roles: roles.map((r) => ({ uuid: r, display: r })),
+        },
+    } as any;
+}
+
+describe('useReportBuilderPrivileges', () => {
+    it('matches held privileges by name', () => {
+        mockUseSession.mockReturnValue(sessionWith([RB.REPORT_VIEW]));
+        const { current, unmount } = renderHook(() => useReportBuilderPrivileges());
+        expect(current!.has(RB.REPORT_VIEW)).toBe(true);
+        expect(current!.has(RB.REPORT_EDIT)).toBe(false);
+        expect(current!.isAuthenticated).toBe(true);
+        unmount();
+    });
+
+    it('uses OR semantics like the backend @Authorized({a, b})', () => {
+        mockUseSession.mockReturnValue(sessionWith([RB.REPORT_ADD]));
+        const { current, unmount } = renderHook(() => useReportBuilderPrivileges());
+        expect(current!.has(RB.REPORT_ADD, RB.REPORT_EDIT)).toBe(true);
+        expect(current!.hasAll(RB.REPORT_ADD, RB.REPORT_EDIT)).toBe(false);
+        unmount();
+    });
+
+    it('treats the System Developer role as superuser', () => {
+        mockUseSession.mockReturnValue(sessionWith([], ['System Developer']));
+        const { current, unmount } = renderHook(() => useReportBuilderPrivileges());
+        expect(current!.isSuperUser).toBe(true);
+        expect(current!.has(RB.ETLMONITOR_PURGE)).toBe(true);
+        expect(current!.hasAll(RB.PACKAGE_IMPORT, RB.PACKAGE_EXPORT)).toBe(true);
+        unmount();
+    });
+
+    it('exposes convenience flags', () => {
+        mockUseSession.mockReturnValue(
+            sessionWith([RB.REPORT_VIEW, RB.REPORT_RUN, RB.PACKAGE_EXPORT]),
+        );
+        const { current, unmount } = renderHook(() => useReportBuilderPrivileges());
+        expect(current!.canAuthor).toBe(false);
+        expect(current!.canRun).toBe(true);
+        expect(current!.canPublish).toBe(true);
+        expect(current!.canManageEtl).toBe(false);
+        unmount();
+    });
+
+    it('is false on everything for an unauthenticated session', () => {
+        mockUseSession.mockReturnValue({ authenticated: false, user: undefined });
+        const { current, unmount } = renderHook(() => useReportBuilderPrivileges());
+        expect(current!.isAuthenticated).toBe(false);
+        expect(current!.has(RB.REPORT_VIEW)).toBe(false);
+        unmount();
+    });
+});

package/src/hooks/use-report-builder-privileges.ts

@@ -0,0 +1,58 @@
+import { useCallback, useMemo } from 'react';
+import { useSession } from '@openmrs/esm-framework';
+import { RB } from '../constants/privileges';
+
+const SUPERUSER_ROLE = 'System Developer';
+
+/**
+ * Privileges of the signed-in user, as resolved by the backend session endpoint
+ * (inherited roles already expanded). Backed by the framework session store —
+ * the same fetch the SPA shell and headers already use — so there is no extra
+ * network call and values refresh automatically on re-login.
+ *
+ * `has` uses OR semantics: has(RB.REPORT_ADD, RB.REPORT_EDIT) is true when the
+ * user holds either, mirroring the backend's @Authorized({a, b}) behaviour.
+ */
+export function useReportBuilderPrivileges() {
+    const session = useSession();
+    const user = session?.user;
+
+    const held = useMemo(() => {
+        const names = new Set<string>();
+        for (const privilege of user?.privileges ?? []) {
+            names.add(privilege.name);
+            names.add(privilege.display);
+        }
+        return names;
+    }, [user]);
+
+    const isSuperUser = useMemo(
+        () => !!user?.roles?.some((role) => role.display === SUPERUSER_ROLE),
+        [user],
+    );
+
+    const has = useCallback(
+        (...needed: string[]) =>
+            needed.length === 0 || isSuperUser || needed.some((privilege) => held.has(privilege)),
+        [held, isSuperUser],
+    );
+
+    const hasAll = useCallback(
+        (...needed: string[]) =>
+            needed.length === 0 || isSuperUser || needed.every((privilege) => held.has(privilege)),
+        [held, isSuperUser],
+    );
+
+    return {
+        /** has(RB.X, RB.Y) — true when the user holds ANY of the privileges. */
+        has,
+        /** hasAll(RB.X, RB.Y) — true only when the user holds ALL of the privileges. */
+        hasAll,
+        isSuperUser,
+        isAuthenticated: !!session?.authenticated,
+        canAuthor: has(RB.REPORT_ADD, RB.REPORT_EDIT),
+        canRun: has(RB.REPORT_RUN),
+        canPublish: has(RB.PACKAGE_IMPORT, RB.PACKAGE_EXPORT),
+        canManageEtl: has(RB.ETLSOURCE_ADD, RB.ETLSOURCE_EDIT, RB.ETLMONITOR_ADD, RB.ETLMONITOR_EDIT),
+    };
+}

package/src/resources/etl-monitor/etl-monitor-test.api.ts

@@ -221,9 +221,12 @@ export async function testEndpointConnection(
 
     if (error?.response?.status === 403) {
       return {
-        success: false,
-        error: 'Permission denied. You may not have the required privileges to test endpoints.',
+        // PrivilegeError (from the omrs* helpers) already carries a user-friendly message.
+        error:
+          error?.message ??
+          'Permission denied. You may not have the required privileges to test endpoints.',
         errorCode: 'FORBIDDEN',
+        success: false,
         durationMs,
         testedAt: new Date().toISOString(),
       };

package/src/resources/etl-task/etl-task.api.ts

@@ -6,14 +6,20 @@
 import { openmrsFetch } from '@openmrs/esm-framework';
 import type { OpenMRSTaskDefinition, ETLTaskExecutionResponse } from './etl-task.types';
 
+// These are OpenMRS core endpoints (scheduler), not reportbuilder ones - a 403 here
+// carries a core privilege name, which the error normalizer passes through verbatim.
+import { guardRejection } from '../../utils/api-error.utils';
+
 /**
  * Fetch all available OpenMRS task definitions (with scheduler metadata)
  */
 export async function fetchAllTaskDefinitions(signal?: AbortSignal): Promise<OpenMRSTaskDefinition[]> {
   try {
-    const response = await openmrsFetch(
-      '/ws/rest/v1/taskdefinition?v=custom:(uuid,name,description,taskClass,started,lastExecutionTime,repeatInterval)',
-      { signal },
+    const response = await guardRejection(
+      openmrsFetch(
+        '/ws/rest/v1/taskdefinition?v=custom:(uuid,name,description,taskClass,started,lastExecutionTime,repeatInterval)',
+        { signal },
+      ),
     );
     const data = await response.json();
     return data.results || [];
@@ -62,16 +68,18 @@ export async function fetchConfiguredTasks(
  */
 export async function executeETLTask(taskName: string): Promise<ETLTaskExecutionResponse> {
   try {
-    const response = await openmrsFetch('/ws/rest/v1/taskaction', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-      },
-      body: {
-        action: 'runtask',
-        tasks: [taskName],
-      },
-    });
+    const response = await guardRejection(
+      openmrsFetch('/ws/rest/v1/taskaction', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: {
+          action: 'runtask',
+          tasks: [taskName],
+        },
+      }),
+    );
 
     if (response.status !== 201) {
       throw new Error(`Task execution failed with status ${response.status}`);

package/src/resources/legacy-reports/legacy-reports.api.ts

@@ -1,23 +1,9 @@
 import { openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
 
-const RESOURCE = '/reportbuilder/legacy';
-
-async function omrsGet<T>(path: string, signal?: AbortSignal): Promise<T> {
-  const url = `${restBaseUrl}${path.startsWith('/') ? path : `/${path}`}`;
-  const res = await openmrsFetch<T>(url, { signal });
-  return res.data;
-}
+import { guardRejection } from '../../utils/api-error.utils';
+import { omrsGet, omrsPost } from '../openmrs-api';
 
-async function omrsPost<T>(path: string, body: any, signal?: AbortSignal): Promise<T> {
-  const url = `${restBaseUrl}${path.startsWith('/') ? path : `/${path}`}`;
-  const res = await openmrsFetch<T>(url, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body,
-    signal,
-  });
-  return res.data;
-}
+const RESOURCE = '/reportbuilder/legacy';
 
 export type LegacyReportDto = {
   uuid: string;
@@ -122,11 +108,13 @@ export async function uploadLegacyReport(
 
   const url = `${restBaseUrl}${RESOURCE}/upload`;
 
-  const response = await openmrsFetch(url, {
-    method: 'POST',
-    body: formData,
-    signal,
-  });
+  const response = await guardRejection(
+    openmrsFetch(url, {
+      method: 'POST',
+      body: formData,
+      signal,
+    }),
+  );
 
   if (!response.ok) {
     throw new Error(`HTTP error! status: ${response.status}`);

package/src/resources/openmrs-api.ts

@@ -1,24 +1,40 @@
 import { openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
 
+import { normalizeApiError } from '../utils/api-error.utils';
+
+async function run<T>(request: () => Promise<T>): Promise<T> {
+    try {
+        return await request();
+    } catch (error) {
+        throw normalizeApiError(error);
+    }
+}
+
 export async function omrsGet<T>(path: string, signal?: AbortSignal): Promise<T> {
-    const url = `${restBaseUrl}${path.startsWith('/') ? path : `/${path}`}`;
-    const res = await openmrsFetch<T>(url, { signal });
-    return res.data;
+    return run(async () => {
+        const url = `${restBaseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+        const res = await openmrsFetch<T>(url, { signal });
+        return res.data;
+    });
 }
 
 export async function omrsPost<T>(path: string, body: any, signal?: AbortSignal): Promise<T> {
-    const url = `${restBaseUrl}${path.startsWith('/') ? path : `/${path}`}`;
-    const res = await openmrsFetch<T>(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body,
-        signal,
+    return run(async () => {
+        const url = `${restBaseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+        const res = await openmrsFetch<T>(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body,
+            signal,
+        });
+        return res.data;
     });
-    return res.data;
 }
 
 export async function omrsDelete<T>(path: string, signal?: AbortSignal): Promise<T> {
-    const url = `${restBaseUrl}${path.startsWith('/') ? path : `/${path}`}`;
-    const res = await openmrsFetch<T>(url, { method: 'DELETE', signal });
-    return res.data;
-}
+    return run(async () => {
+        const url = `${restBaseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+        const res = await openmrsFetch<T>(url, { method: 'DELETE', signal });
+        return res.data;
+    });
+}

package/src/resources/report-section/section-preview.api.ts

@@ -1,5 +1,7 @@
 import { openmrsFetch } from '@openmrs/esm-framework';
 
+import { guardRejection } from '../../utils/api-error.utils';
+
 export type SectionPreviewRequest = {
   sectionUuid: string;
   indicatorUuid?: string;
@@ -10,12 +12,14 @@ export type SectionPreviewRequest = {
 };
 
 export async function previewSection(body: SectionPreviewRequest, signal?: AbortSignal) {
-  const { data } = await openmrsFetch('/ws/rest/v1/reportbuilder/sectionpreview', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body,
-    signal,
-  });
+  const { data } = await guardRejection(
+    openmrsFetch('/ws/rest/v1/reportbuilder/sectionpreview', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body,
+      signal,
+    }),
+  );
 
   return data;
 }

package/src/routes/report-builder.routes.tsx

@@ -31,55 +31,120 @@ import LinelistRunReport from '../components/linelist/linelist-run-report.page.c
 
 import { ImportExportPage } from '../components/import-export';
 
+import PrivilegeRoute from '../components/security/privilege-route.component';
+import { ROUTE_PRIVILEGES } from '../constants/privileges';
+
+/** Wraps a route element with its required privileges (see ROUTE_PRIVILEGES). */
+const guard = (route: keyof typeof ROUTE_PRIVILEGES, element: React.ReactNode) => (
+    <PrivilegeRoute required={ROUTE_PRIVILEGES[route]}>{element}</PrivilegeRoute>
+);
+
 const ReportBuilderRoutes: React.FC = () => {
     return (
         <Routes>
             <Route element={<ReportBuilderShell />}>
                 {/* Home / landing */}
-                <Route path="/" element={<ReportBuilderLandingPage />} />
+                <Route path="/" element={guard('/', <ReportBuilderLandingPage />)} />
 
                 {/* Reports */}
-                <Route path="/reports" element={<ReportDashboardPage />} />
+                <Route path="/reports" element={guard('/reports', <ReportDashboardPage />)} />
 
                 {/* Create / edit report */}
-                <Route path="/new" element={<ReportEditorPage />} />
-                <Route path="/edit/:reportId" element={<ReportEditorPage />} />
+                <Route path="/new" element={guard('/new', <ReportEditorPage />)} />
+                <Route
+                    path="/edit/:reportId"
+                    element={guard('/edit/:reportId', <ReportEditorPage />)}
+                />
 
                 {/* Indicators / sections */}
-                <Route path="/indicators" element={<IndicatorsPage />} />
-                <Route path="/sections" element={<SectionsPage />} />
+                <Route path="/indicators" element={guard('/indicators', <IndicatorsPage />)} />
+                <Route path="/sections" element={guard('/sections', <SectionsPage />)} />
 
                 {/* Run */}
-                <Route path="/run" element={<ReportVisualizerPage />} />
-                <Route path="/run-reports" element={<ReportVisualizerPage />} />
+                <Route path="/run" element={guard('/run', <ReportVisualizerPage />)} />
+                <Route
+                    path="/run-reports"
+                    element={guard('/run-reports', <ReportVisualizerPage />)}
+                />
 
                 {/* Admin */}
-                <Route path="/admin" element={<AdminPage />} />
-                <Route path="/admin/report-categories" element={<ReportCategoriesPage />} />
-                <Route path="/admin/age-categories" element={<AgeCategoriesPage />} />
-                <Route path="/admin/age-groups" element={<AgeGroupsPage />} />
-                <Route path="/admin/report-library" element={<ReportLibraryPage />} />
-                <Route path="/admin/etl-sources" element={<ETLSourcesPage />} />
-                <Route path="/admin/etl-tasks" element={<ETLTasksPage />} />
-                <Route path="/admin/etl-monitors" element={<ETLMonitorsPage />} />
-                <Route path="/admin/etl-monitors/builder" element={<EtlMonitorBuilderPage />} />
-                <Route path="/admin/etl-browser" element={<EtlBrowserPage />} />
-                <Route path="/admin/dashboards" element={<DashboardsAdminPage />} />
-                <Route path="/dashboards" element={<DashboardsPage />} />
-                <Route path="/dashboards/:code" element={<DashboardRendererPage />} />
-                <Route path="/etl-dashboard" element={<EtlDashboardPage />} />
+                <Route path="/admin" element={guard('/admin', <AdminPage />)} />
+                <Route
+                    path="/admin/report-categories"
+                    element={guard('/admin/report-categories', <ReportCategoriesPage />)}
+                />
+                <Route
+                    path="/admin/age-categories"
+                    element={guard('/admin/age-categories', <AgeCategoriesPage />)}
+                />
+                <Route
+                    path="/admin/age-groups"
+                    element={guard('/admin/age-groups', <AgeGroupsPage />)}
+                />
+                <Route
+                    path="/admin/report-library"
+                    element={guard('/admin/report-library', <ReportLibraryPage />)}
+                />
+                <Route
+                    path="/admin/etl-sources"
+                    element={guard('/admin/etl-sources', <ETLSourcesPage />)}
+                />
+                <Route
+                    path="/admin/etl-tasks"
+                    element={guard('/admin/etl-tasks', <ETLTasksPage />)}
+                />
+                <Route
+                    path="/admin/etl-monitors"
+                    element={guard('/admin/etl-monitors', <ETLMonitorsPage />)}
+                />
+                <Route
+                    path="/admin/etl-monitors/builder"
+                    element={guard('/admin/etl-monitors/builder', <EtlMonitorBuilderPage />)}
+                />
+                <Route
+                    path="/admin/etl-browser"
+                    element={guard('/admin/etl-browser', <EtlBrowserPage />)}
+                />
+                <Route
+                    path="/admin/dashboards"
+                    element={guard('/admin/dashboards', <DashboardsAdminPage />)}
+                />
+                <Route path="/dashboards" element={guard('/dashboards', <DashboardsPage />)} />
+                <Route
+                    path="/dashboards/:code"
+                    element={guard('/dashboards/:code', <DashboardRendererPage />)}
+                />
+                <Route
+                    path="/etl-dashboard"
+                    element={guard('/etl-dashboard', <EtlDashboardPage />)}
+                />
 
                 {/* Data themes now accessed under Admin */}
-                <Route path="/admin/themes" element={<DataThemesPage />} />
+                <Route
+                    path="/admin/themes"
+                    element={guard('/admin/themes', <DataThemesPage />)}
+                />
 
                 {/* Linelist Reports */}
-                <Route path="/linelist" element={<LinelistReportsPage />} />
-                <Route path="/linelist/new" element={<LinelistBuilderWorkspace />} />
-                <Route path="/linelist/edit/:reportId" element={<LinelistBuilderWorkspace />} />
-                <Route path="/linelist/run/:reportId" element={<LinelistRunReport />} />
+                <Route path="/linelist" element={guard('/linelist', <LinelistReportsPage />)} />
+                <Route
+                    path="/linelist/new"
+                    element={guard('/linelist/new', <LinelistBuilderWorkspace />)}
+                />
+                <Route
+                    path="/linelist/edit/:reportId"
+                    element={guard('/linelist/edit/:reportId', <LinelistBuilderWorkspace />)}
+                />
+                <Route
+                    path="/linelist/run/:reportId"
+                    element={guard('/linelist/run/:reportId', <LinelistRunReport />)}
+                />
 
                 {/* Import / Export */}
-                <Route path="/import-export" element={<ImportExportPage />} />
+                <Route
+                    path="/import-export"
+                    element={guard('/import-export', <ImportExportPage />)}
+                />
 
                 {/* Optional backward compatibility */}
                 <Route path="/themes" element={<Navigate to="/admin/themes" replace />} />

package/src/routes.json

@@ -15,7 +15,8 @@
       "slot": "system-admin-page-card-link-slot",
       "component": "reportBuilderAdminLink",
       "online": true,
-      "offline": false
+      "offline": false,
+      "privileges": "Task: reportbuilder.report.view"
     },
     {
       "component": "confirmModal",
@@ -24,4 +25,4 @@
       "offline": true
     }
   ]
-}
+}