@openmrs/esm-report-builder 0.1.1-pre.101

package/src/types/theme/data-theme.types.ts

@@ -0,0 +1,88 @@
+// src/report-builder/types/theme/data-theme.types.ts
+
+export type MainDataDomain =
+    | 'OBSERVATIONS'
+    | 'TEST_ORDERS'
+    | 'MEDICATION_ORDERS'
+    | 'APPOINTMENTS'
+    | 'MEDICATION_DISPENSE'
+    | 'DIAGNOSIS';
+
+export type FieldType = 'string' | 'number' | 'date' | 'datetime' | 'boolean' | 'coded' | 'json';
+
+export type ThemeField = {
+  key: string;
+  label: string;
+  expr: string;
+  type: FieldType;
+};
+
+export type ConditionHandler =
+    | 'CONCEPT_SEARCH'
+    | 'QUESTION_ANSWER_CONCEPT_SEARCH'
+    | 'TEXT'
+    | 'NUMBER'
+    | 'DATE_RANGE'
+    | 'BOOLEAN'
+    | 'LOCATION_PICKER'
+    | 'CODED_LIST';
+
+/**
+ * Theme-side operator tokens (legacy + UI-friendly).
+ * NOTE: SQL generation will normalize these to real SQL operators.
+ */
+export type ConditionOperator = 'EQUALS' | 'IN' | 'NOT_IN' | 'LIKE' | 'BETWEEN' | 'GTE' | 'LTE';
+
+export type ConditionValueType =
+    | 'conceptUuid'
+    | 'conceptId'
+    | 'string'
+    | 'number'
+    | 'date'
+    | 'datetime'
+    | 'boolean';
+
+export type ThemeCondition = {
+  key: string;
+  label: string;
+  handler: ConditionHandler;
+  column: string;
+  operator: ConditionOperator;
+  valueType: ConditionValueType;
+};
+
+export type DataThemeConfig = {
+  sourceTable: string;
+  patientIdColumn: string;
+  dateColumn: string;
+  locationColumn?: string;
+
+  joins?: Array<{ alias: string; joinSql: string }>;
+  defaultFilters?: string[];
+
+  fields: ThemeField[];
+
+  conditions?: ThemeCondition[];
+
+  conditionColumns?: Record<string, string>;
+};
+
+export type DataTheme = {
+  uuid?: string;
+  name: string;
+  description?: string;
+  code: string;
+  domain: MainDataDomain;
+  configJson: string;
+  metaJson?: string;
+  retired?: boolean;
+};
+
+export type DataThemeRow = {
+  uuid: string;
+  name: string;
+  code: string;
+  domain: MainDataDomain;
+  description?: string;
+  retired?: boolean;
+};

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

@@ -0,0 +1,147 @@
+import { describe, expect, it, vi } from 'vitest';
+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)', async () => {
+    vi.resetModules();
+    const fresh = await import('./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}`)}`;
+}

package/src/utils/config-enhancer.ts

@@ -0,0 +1,62 @@
+/**
+ * Config Enhancement Utilities
+ *
+ * Utilities for enhancing configuration objects with metadata
+ * for debugging and visibility in JSON previews.
+ */
+
+import type { LinelistReportDefinitionConfig } from '../types/linelist-types';
+import type { LinelistReportDraft } from '../types/linelist-types';
+
+/**
+ * Enhance config for preview by adding column metadata (id, position)
+ * This helps with debugging and visibility in the JSON preview
+ */
+export function enhanceConfigForPreview(
+  config: LinelistReportDefinitionConfig,
+  draft: LinelistReportDraft
+): LinelistReportDefinitionConfig {
+  const enhanced = { ...config };
+
+  // Add column metadata to dataSetDefinitions columns
+  if (enhanced.dataSetDefinitions && enhanced.dataSetDefinitions[0]) {
+    const dataSetDef = enhanced.dataSetDefinitions[0];
+    const columnsWithMetadata = dataSetDef.columns.map((col: any, idx: number) => {
+      const draftCol = draft.columns.find(c => c.name === col.name);
+      return {
+        ...col,
+        _metadata: {
+          id: draftCol?.id || `col-${idx}`,
+          position: draftCol?.sortOrder ?? idx,
+        },
+      };
+    });
+    (enhanced as any).dataSetDefinitions[0] = {
+      ...dataSetDef,
+      columns: columnsWithMetadata,
+    };
+  }
+
+  // Also add metadata to dataSources columns
+  if (enhanced.dataSources) {
+    (enhanced as any).dataSources = enhanced.dataSources.map((ds: any) => {
+      if (ds.columns) {
+        const columnsWithMetadata: any = {};
+        Object.entries(ds.columns).forEach(([name, col]: [string, any]) => {
+          const draftCol = draft.columns.find(c => c.name === name);
+          columnsWithMetadata[name] = {
+            ...col,
+            _metadata: {
+              id: draftCol?.id,
+              position: draftCol?.sortOrder,
+            },
+          };
+        });
+        return { ...ds, columns: columnsWithMetadata };
+      }
+      return ds;
+    });
+  }
+
+  return enhanced;
+}

package/src/utils/etl-browser/etl-browser.util.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it } from 'vitest';
+import {
+  groupTablesBySource,
+  tableNameMatchesPattern,
+  quoteTableIdentifier,
+  buildTablePreviewSql,
+  escapeCsvCell,
+  toCsv,
+  summarizeColumns,
+  OTHER_GROUP_ID,
+} from './';
+import type { SchemaTable } from '../../resources/theme/etl-schema.api';
+import type { ETLSourceDto } from '../../resources/etl-source/etl-source.api';
+import type { TableColumn } from '../../resources/theme/etl-table-meta.api';
+
+function table(name: string, extra: Partial<SchemaTable> = {}): SchemaTable {
+  return { name, ...extra };
+}
+
+function source(uuid: string, name: string, tablePatterns: string, extra: Partial<ETLSourceDto> = {}): ETLSourceDto {
+  return { uuid, name, tablePatterns, ...extra } as ETLSourceDto;
+}
+
+describe('tableNameMatchesPattern', () => {
+  it('matches prefixes case-insensitively', () => {
+    expect(tableNameMatchesPattern('mamba_visits', 'mamba')).toBe(true);
+    expect(tableNameMatchesPattern('Mamba_Visits', 'MAMBA')).toBe(true);
+    expect(tableNameMatchesPattern('other_table', 'mamba')).toBe(false);
+  });
+
+  it('treats % and _ as live wildcards like the server LIKE', () => {
+    expect(tableNameMatchesPattern('fact_encounter', 'fact_%')).toBe(true);
+    expect(tableNameMatchesPattern('fact_x', 'fact_')).toBe(true);
+    expect(tableNameMatchesPattern('fact', 'fact_')).toBe(false);
+  });
+
+  it('rejects empty patterns and names', () => {
+    expect(tableNameMatchesPattern('mamba_visits', '   ')).toBe(false);
+    expect(tableNameMatchesPattern('', 'mamba')).toBe(false);
+  });
+});
+
+describe('groupTablesBySource', () => {
+  const sources = [source('uuid-1', 'Mamba', 'mamba'), source('uuid-2', 'Analytics', 'analytics, etl_flattened')];
+
+  it('groups tables under the first matching source', () => {
+    const tables = [table('mamba_visits'), table('mamba_ops'), table('analytics_daily'), table('etl_flattened_x')];
+    const { groups, other } = groupTablesBySource(tables, sources);
+
+    expect(groups[0].tables.map((t) => t.name)).toEqual(['mamba_visits', 'mamba_ops']);
+    expect(groups[1].tables.map((t) => t.name)).toEqual(['analytics_daily', 'etl_flattened_x']);
+    expect(other.tables).toHaveLength(0);
+  });
+
+  it('ignores inactive or voided sources', () => {
+    const sourcesWithInactive = [...sources, source('uuid-3', 'Retired', 'fact_', { active: false })];
+    const { groups, other } = groupTablesBySource([table('fact_encounter')], sourcesWithInactive);
+
+    expect(groups.find((g) => g.id === 'uuid-3')).toBeUndefined();
+    expect(other.tables.map((t) => t.name)).toEqual(['fact_encounter']);
+  });
+
+  it('collects unmatched tables in Other', () => {
+    const { other } = groupTablesBySource([table('misc_things'), table('mamba_visits')], sources);
+    expect(other.id).toBe(OTHER_GROUP_ID);
+    expect(other.tables.map((t) => t.name)).toEqual(['misc_things']);
+  });
+
+  it('keeps empty groups for sources that match nothing', () => {
+    const { groups } = groupTablesBySource([table('misc_things')], sources);
+    expect(groups).toHaveLength(2);
+    expect(groups.every((g) => g.tables.length === 0)).toBe(true);
+  });
+
+  it('handles empty inputs', () => {
+    expect(groupTablesBySource([], sources).other.tables).toHaveLength(0);
+    const { groups, other } = groupTablesBySource([table('x')], []);
+    expect(groups).toHaveLength(0);
+    expect(other.tables).toHaveLength(1);
+  });
+});
+
+describe('quoteTableIdentifier / buildTablePreviewSql', () => {
+  it('backtick-quotes plain names', () => {
+    expect(quoteTableIdentifier('fact_encounter')).toBe('`fact_encounter`');
+    expect(buildTablePreviewSql('fact_encounter')).toBe('SELECT * FROM `fact_encounter`');
+  });
+
+  it('doubles embedded backticks', () => {
+    expect(quoteTableIdentifier('we`ird')).toBe('`we``ird`');
+  });
+
+  it('throws on empty names', () => {
+    expect(() => quoteTableIdentifier('')).toThrow();
+    expect(() => quoteTableIdentifier('   ')).toThrow();
+  });
+});
+
+describe('escapeCsvCell / toCsv', () => {
+  it('passes plain cells through and renders null as empty', () => {
+    expect(escapeCsvCell('plain')).toBe('plain');
+    expect(escapeCsvCell(-15)).toBe('-15');
+    expect(escapeCsvCell(null)).toBe('');
+    expect(escapeCsvCell(undefined)).toBe('');
+  });
+
+  it('quotes cells with special characters and doubles quotes', () => {
+    expect(escapeCsvCell('a,b')).toBe('"a,b"');
+    expect(escapeCsvCell('say "hi"')).toBe('"say ""hi"""');
+    expect(escapeCsvCell('line\nbreak')).toBe('"line\nbreak"');
+  });
+
+  it('guards formula-injection prefixes but keeps negatives', () => {
+    expect(escapeCsvCell('=cmd')).toBe("'=cmd");
+    expect(escapeCsvCell('+2')).toBe("'+2");
+    expect(escapeCsvCell('@risk')).toBe("'@risk");
+  });
+
+  it('serializes header plus rows', () => {
+    expect(
+      toCsv(
+        ['a', 'b'],
+        [
+          [1, 'x,y'],
+          [null, 'z'],
+        ],
+      ),
+    ).toBe('a,b\n1,"x,y"\n,z');
+  });
+});
+
+describe('summarizeColumns', () => {
+  const columns: TableColumn[] = [
+    { name: 'id', type: 'int' },
+    { name: 'patient_id', type: 'int' },
+    { name: 'name', type: 'varchar' },
+    { name: 'note', type: 'text' },
+    { name: 'flag' },
+  ];
+
+  it('counts totals and breaks down by type, sorted by count desc', () => {
+    const summary = summarizeColumns(columns);
+    expect(summary.total).toBe(5);
+    expect(summary.byType[0]).toEqual({ type: 'int', count: 2 });
+    expect(summary.byType.map((t) => t.type)).toEqual(['int', 'text', 'unknown', 'varchar']);
+  });
+
+  it('handles empty input', () => {
+    expect(summarizeColumns([])).toEqual({ total: 0, byType: [] });
+  });
+});

package/src/utils/etl-browser/export-csv.util.ts

@@ -0,0 +1,43 @@
+/**
+ * ETL Data Browser — client-side CSV export for table previews
+ */
+
+import { saveAs } from 'file-saver';
+
+/**
+ * Escape one CSV cell: quote when needed, double embedded quotes, and guard
+ * against spreadsheet formula injection from leading = + @ characters.
+ * (Leading '-' is left alone so negative numbers survive the round-trip.)
+ */
+export function escapeCsvCell(value: unknown): string {
+    if (value === null || value === undefined) return '';
+
+    let str = typeof value === 'object' ? JSON.stringify(value) : String(value);
+
+    if (/^[=+@]/.test(str)) {
+        str = `'${str}`;
+    }
+
+    if (/[",\n\r]/.test(str)) {
+        str = `"${str.replace(/"/g, '""')}"`;
+    }
+
+    return str;
+}
+
+/** Serialize columns + rows to CSV text (\n-separated, header row first). */
+export function toCsv(columns: string[], rows: unknown[][]): string {
+    const lines = [columns.map(escapeCsvCell).join(',')];
+    for (const row of rows ?? []) {
+        lines.push(row.map(escapeCsvCell).join(','));
+    }
+    return lines.join('\n');
+}
+
+/** Build and download a CSV file for a table preview. */
+export function downloadCsv(filename: string, columns: string[], rows: unknown[][]): void {
+    const csv = toCsv(columns, rows);
+    const blob = new Blob([csv], { type: 'text/csv;charset=utf-8' });
+    const dated = `${filename}_${new Date().toISOString().replace(/:/g, '-')}.csv`;
+    saveAs(blob, dated);
+}