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

package/src/utils/api-error.utils.test.ts

@@ -0,0 +1,151 @@
+import { RB } from '../constants/privileges';
+import { guardRejection, normalizeApiError, PrivilegeError } from './api-error.utils';
+
+/** Axios-shaped error factory. */
+function axiosError(status: number, data: unknown, message = 'Request failed with status code ' + status) {
+  return {
+    message,
+    response: { status, data },
+  };
+}
+
+const stubLocation = (partial: Record<string, unknown> = {}) => {
+  // jsdom's location is deletable in the test environment; fall back silently if not.
+  const w = window as any;
+  try {
+    delete w.location;
+    w.location = {
+      href: '',
+      pathname: '/openmrs/spa/report-builder/reports',
+      search: '',
+      ...partial,
+    };
+    // getOpenmrsSpaBase is a window global set by the SPA shell.
+    w.getOpenmrsSpaBase = () => '/openmrs/spa/';
+    w.spaBase = '/openmrs/spa';
+  } catch {
+    /* navigation stays a jsdom no-op log */
+  }
+};
+
+describe('normalizeApiError', () => {
+  it('passes AbortError through untouched', () => {
+    const abort = Object.assign(new Error('The operation was aborted.'), { name: 'AbortError' });
+    expect(normalizeApiError(abort)).toBe(abort);
+  });
+
+  it('is idempotent for PrivilegeError', () => {
+    const already = new PrivilegeError({ status: 403, message: 'x' });
+    expect(normalizeApiError(already)).toBe(already);
+  });
+
+  describe('403 with a reportbuilder privilege in the message', () => {
+    it('builds a friendly message and parses the privilege', () => {
+      const error = normalizeApiError(
+        axiosError(403, {
+          error: { message: `Privilege required: ${RB.REPORT_EDIT}` },
+        }),
+      ) as PrivilegeError;
+
+      expect(error).toBeInstanceOf(PrivilegeError);
+      expect(error.status).toBe(403);
+      expect(error.requiredPrivileges).toEqual([RB.REPORT_EDIT]);
+      expect(error.message).toContain('permission');
+      expect(error.message).toContain('report.edit');
+      expect(error.message).not.toContain('Task:');
+    });
+
+    it('deduplicates repeated privileges and preserves the axios response', () => {
+      const original = axiosError(403, {
+        message: `Privilege required: ${RB.REPORT_ADD} or ${RB.REPORT_ADD}`,
+      });
+      const error = normalizeApiError(original) as PrivilegeError;
+      expect(error.requiredPrivileges).toEqual([RB.REPORT_ADD]);
+      expect(error.response).toEqual(original.response);
+    });
+  });
+
+  describe('403 from non-reportbuilder endpoints', () => {
+    it('keeps the server wording verbatim (e.g. core task scheduler)', () => {
+      const error = normalizeApiError(
+        axiosError(403, { error: { message: 'Privilege required: Manage Scheduler' } }),
+      ) as PrivilegeError;
+
+      expect(error).toBeInstanceOf(PrivilegeError);
+      expect(error.status).toBe(403);
+      expect(error.requiredPrivileges).toBeUndefined();
+      expect(error.message).toBe('Privilege required: Manage Scheduler');
+    });
+
+    it('falls back to a generic message when nothing readable is present', () => {
+      const error = normalizeApiError({ message: '', response: { status: 403, data: null } }) as PrivilegeError;
+      expect(error).toBeInstanceOf(PrivilegeError);
+      expect(error.message).toContain('permission');
+    });
+
+    it('keeps the axios message when there is no body', () => {
+      const error = normalizeApiError(axiosError(403, null)) as PrivilegeError;
+      expect(error.message).toBe('Request failed with status code 403');
+    });
+  });
+
+  describe('401 (expired session)', () => {
+    it('marks the error as an auth error and redirects to the SPA login page', () => {
+      stubLocation();
+      const error = normalizeApiError(
+        axiosError(401, { error: { message: 'Session has expired' } }),
+      ) as PrivilegeError;
+
+      expect(error).toBeInstanceOf(PrivilegeError);
+      expect(error.isAuthError).toBe(true);
+      expect(error.status).toBe(401);
+      expect(error.message).toMatch(/session/i);
+      expect(window.location.href).toContain('/openmrs/spa/login');
+      expect(window.location.href).toContain('returnTo=');
+    });
+
+    it('does not redirect when already on the login page', () => {
+      stubLocation({ pathname: '/openmrs/spa/login', href: 'about-to-stay' });
+      normalizeApiError(axiosError(401, null));
+      expect(window.location.href).toBe('about-to-stay');
+    });
+  });
+
+  it('maps other statuses to a generic error carrying the server message', () => {
+    const error = normalizeApiError(
+      axiosError(500, { error: { message: 'Boom' } }),
+    ) as Error & { status?: number };
+    expect(error).not.toBeInstanceOf(PrivilegeError);
+    expect(error.message).toBe('Boom');
+    expect(error.status).toBe(500);
+  });
+});
+
+describe('guardRejection', () => {
+  it('returns the resolved value', async () => {
+    await expect(guardRejection(Promise.resolve({ data: 42 }))).resolves.toEqual({ data: 42 });
+  });
+
+  it('normalizes rejections', async () => {
+    await expect(
+      guardRejection(Promise.reject(axiosError(403, { error: { message: `Privilege required: ${RB.REPORT_RUN}` } }))),
+    ).rejects.toBeInstanceOf(PrivilegeError);
+  });
+});
+
+describe('redirectToLogin loop guard', () => {
+  it('navigates at most once across repeated calls (module-level latch)', () => {
+    stubLocation();
+    jest.isolateModules(() => {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires -- fresh module instance for the latch test
+      const fresh = require('./api-error.utils');
+      stubLocation();
+      fresh.redirectToLogin();
+      expect(window.location.href).toContain('/login');
+      // The latch makes further calls no-ops even with a fresh path.
+      stubLocation({ pathname: '/openmrs/spa/report-builder/admin', href: 'unchanged' });
+      fresh.redirectToLogin();
+      expect(window.location.href).toBe('unchanged');
+    });
+  });
+});

package/src/utils/api-error.utils.ts

@@ -0,0 +1,131 @@
+import { RB_PREFIX } from '../constants/privileges';
+
+const RB_PRIVILEGE_REGEX = new RegExp(`${RB_PREFIX}[a-z.]+`, 'g');
+
+/**
+ * Thrown by the omrs* helpers (and guarded direct openmrsFetch calls) when the
+ * backend rejects a request for lack of privileges (403) or an expired session
+ * (401). The message is user-facing — pages render `e?.message` directly.
+ */
+export class PrivilegeError extends Error {
+    readonly status?: number;
+    /** Full privilege names parsed out of the server message, e.g. `Task: reportbuilder.report.edit`. */
+    readonly requiredPrivileges?: string[];
+    readonly serverMessage?: string;
+    readonly isAuthError: boolean;
+    /** Original axios response, kept so downstream status checks keep working. */
+    readonly response?: unknown;
+
+    constructor(init: {
+        status?: number;
+        message: string;
+        requiredPrivileges?: string[];
+        serverMessage?: string;
+        isAuthError?: boolean;
+        response?: unknown;
+    }) {
+        super(init.message);
+        this.name = 'PrivilegeError';
+        this.status = init.status;
+        this.requiredPrivileges = init.requiredPrivileges;
+        this.serverMessage = init.serverMessage;
+        this.isAuthError = init.isAuthError ?? false;
+        this.response = init.response;
+    }
+}
+
+function extractServerMessage(error: any): string {
+    const data = error?.response?.data;
+    if (typeof data === 'string') {
+        return data;
+    }
+    return data?.error?.message ?? data?.message ?? error?.message ?? '';
+}
+
+/**
+ * Maps raw openmrsFetch (axios) rejections to friendly errors:
+ * - 401: session expired -> friendly message + one redirect to the login page.
+ * - 403 carrying `Task: reportbuilder.*` -> PrivilegeError naming the privilege.
+ * - other 403s (e.g. OpenMRS core endpoints): keep the server's own wording.
+ * - aborts/cancellations pass through untouched so page AbortController filters keep working.
+ */
+export function normalizeApiError(error: any, fallbackMessage = 'Request failed'): Error {
+    if (error?.name === 'AbortError' || error?.code === 'ERR_CANCELED') {
+        return error;
+    }
+    if (error instanceof PrivilegeError) {
+        return error;
+    }
+
+    const status: number | undefined = error?.response?.status;
+    const serverMessage = extractServerMessage(error);
+
+    if (status === 401) {
+        redirectToLogin();
+        return new PrivilegeError({
+            status: 401,
+            isAuthError: true,
+            serverMessage,
+            response: error?.response,
+            message: 'Your session has expired. Please sign in again.',
+        });
+    }
+
+    if (status === 403) {
+        const matches = serverMessage.match(RB_PRIVILEGE_REGEX) ?? [];
+        if (matches.length > 0) {
+            const requiredPrivileges = [...new Set(matches)];
+            const names = requiredPrivileges.map((privilege) => privilege.replace(RB_PREFIX, '')).join(', ');
+            return new PrivilegeError({
+                status: 403,
+                requiredPrivileges,
+                serverMessage,
+                response: error?.response,
+                message: `You do not have permission to perform this action. Required privilege: ${names}.`,
+            });
+        }
+        return new PrivilegeError({
+            status: 403,
+            serverMessage,
+            response: error?.response,
+            message: serverMessage || 'You do not have permission to perform this action.',
+        });
+    }
+
+    const generic = new Error(serverMessage || fallbackMessage) as Error & {
+        status?: number;
+        response?: unknown;
+    };
+    generic.status = status;
+    generic.response = error?.response;
+    return generic;
+}
+
+/** Wraps a promise from a direct openmrsFetch call so rejections are normalized. */
+export async function guardRejection<T>(promise: Promise<T>): Promise<T> {
+    try {
+        return await promise;
+    } catch (error) {
+        throw normalizeApiError(error);
+    }
+}
+
+let redirecting = false;
+
+/** Sends the browser to the SPA login page. Loop-guarded: skipped when already
+ * on /login and latched so parallel 401s cause a single navigation. */
+export function redirectToLogin(): void {
+    if (typeof window === 'undefined' || redirecting) {
+        return;
+    }
+    const { pathname, search } = window.location;
+    if (pathname.includes('/login')) {
+        return;
+    }
+    redirecting = true;
+    const base =
+        typeof window.getOpenmrsSpaBase === 'function'
+            ? window.getOpenmrsSpaBase()
+            : `${window.spaBase}/`;
+    window.location.href = `${base}login?returnTo=${encodeURIComponent(`${pathname}${search}`)}`;
+}