@kenyaemr/esm-etims-app 5.4.5-pre.1109

package/src/transaction/etims-transaction-table.component.tsx

@@ -0,0 +1,450 @@
+import React, { useCallback, useMemo, useState } from 'react';
+import {
+  DataTable,
+  DataTableSkeleton,
+  Dropdown,
+  OverflowMenu,
+  OverflowMenuItem,
+  Pagination,
+  Table,
+  TableBody,
+  TableCell,
+  TableContainer,
+  TableHead,
+  TableHeader,
+  TableRow,
+  TableToolbar,
+  TableToolbarContent,
+  TableToolbarSearch,
+  Tag,
+  type DataTableHeader,
+} from '@carbon/react';
+import {
+  ErrorCard,
+  formatDatetime,
+  launchWorkspace2,
+  parseDate,
+  showModal,
+  showSnackbar,
+  useDebounce,
+  usePaginationInfo,
+  UserHasAccess,
+} from '@openmrs/esm-framework';
+import { useTranslation } from 'react-i18next';
+import {
+  downloadEtimsTaxInvoice,
+  isConfirmed,
+  isReactivatable,
+  isReconcilable,
+  isRetryable,
+  useEtimsTransactions,
+} from './etims-transaction.resource';
+import type { EtimsTransaction, EtimsTransactionStatus } from './etims-transaction.types';
+import styles from './etims-transaction-table.scss';
+
+const DEFAULT_PAGE_SIZE = 10;
+const PAGE_SIZE_OPTIONS = [10, 20, 50, 100];
+
+type StatusFilter = 'ALL' | EtimsTransactionStatus;
+
+type TransactionRow = {
+  id: string;
+  billId: string;
+  transactionType: string;
+  status: string;
+  traderInvoiceNumber: string;
+  kraInvoiceNumber: string;
+  resultMessage: string;
+  attemptCount: string;
+  dateCreated: string;
+  confirmedAt: string;
+};
+
+const displayValue = (value?: string | number | boolean | null) => {
+  if (value === null || value === undefined || value === '') {
+    return '--';
+  }
+
+  return String(value);
+};
+
+const formatNullableDatetime = (value?: string | null) => {
+  if (!value) {
+    return '--';
+  }
+
+  try {
+    return formatDatetime(parseDate(value), { mode: 'standard', noToday: true });
+  } catch {
+    return value;
+  }
+};
+
+const statusTagType = (status?: string | null): 'green' | 'red' | 'blue' | 'cyan' | 'magenta' | 'purple' | 'gray' => {
+  if (status === 'CONFIRMED') {
+    return 'green';
+  }
+  if (status === 'PERMANENTLY_FAILED' || status === 'ACTION_REQUIRED') {
+    return 'red';
+  }
+  if (status === 'RECONCILIATION_REQUIRED') {
+    return 'magenta';
+  }
+  if (status === 'RETRY') {
+    return 'purple';
+  }
+  if (status === 'SUBMITTED' || status === 'PROCESSING') {
+    return 'cyan';
+  }
+  if (status === 'PENDING') {
+    return 'blue';
+  }
+  return 'gray';
+};
+
+const transactionLabel = (transaction: EtimsTransaction) =>
+  transaction.traderInvoiceNumber ?? transaction.kraInvoiceNumber ?? transaction.uuid;
+
+const EtimsTransactionTable: React.FC = () => {
+  const { t } = useTranslation();
+  const [page, setPage] = useState(1);
+  const [pageSize, setPageSize] = useState(DEFAULT_PAGE_SIZE);
+  const [searchTerm, setSearchTerm] = useState('');
+  const [statusFilter, setStatusFilter] = useState<StatusFilter>('ALL');
+  const [isDownloading, setIsDownloading] = useState<string | null>(null);
+  const debouncedSearchTerm = useDebounce(searchTerm, 300);
+  const billIdFilter = /^\d+$/.test(debouncedSearchTerm.trim()) ? debouncedSearchTerm.trim() : undefined;
+  const { transactions, error, isLoading, mutate } = useEtimsTransactions({
+    status: billIdFilter ? 'ALL' : statusFilter,
+    billId: billIdFilter,
+  });
+
+  const statusItems = useMemo(
+    () => [
+      { id: 'ALL', label: t('allStatuses', 'All statuses') },
+      { id: 'PENDING', label: t('pending', 'Pending') },
+      { id: 'PROCESSING', label: t('processing', 'Processing') },
+      { id: 'SUBMITTED', label: t('submitted', 'Submitted') },
+      { id: 'CONFIRMED', label: t('confirmed', 'Confirmed') },
+      { id: 'RETRY', label: t('retry', 'Retry') },
+      { id: 'RECONCILIATION_REQUIRED', label: t('reconciliationRequired', 'Reconciliation required') },
+      { id: 'ACTION_REQUIRED', label: t('actionRequired', 'Action required') },
+      { id: 'PERMANENTLY_FAILED', label: t('permanentlyFailed', 'Permanently failed') },
+      { id: 'CANCELLED', label: t('cancelled', 'Cancelled') },
+    ],
+    [t],
+  );
+
+  const filteredTransactions = useMemo(() => {
+    const query = debouncedSearchTerm.trim().toLowerCase();
+
+    return transactions.filter((transaction) => {
+      if (!billIdFilter && statusFilter !== 'ALL' && transaction.status !== statusFilter) {
+        return false;
+      }
+
+      if (!query || billIdFilter) {
+        return true;
+      }
+
+      return [
+        transaction.billId,
+        transaction.transactionType,
+        transaction.status,
+        transaction.traderInvoiceNumber,
+        transaction.kraInvoiceNumber,
+        transaction.cuInvoiceNumber,
+        transaction.kraReceiptNumber,
+        transaction.resultCode,
+        transaction.resultMessage,
+        transaction.failureCategory,
+      ].some((value) => displayValue(value).toLowerCase().includes(query));
+    });
+  }, [billIdFilter, debouncedSearchTerm, statusFilter, transactions]);
+
+  const pagedTransactions = useMemo(() => {
+    const start = (page - 1) * pageSize;
+    return filteredTransactions.slice(start, start + pageSize);
+  }, [filteredTransactions, page, pageSize]);
+
+  const { pageSizes } = usePaginationInfo(
+    DEFAULT_PAGE_SIZE,
+    filteredTransactions.length,
+    page,
+    pagedTransactions.length,
+  );
+
+  const headers: Array<DataTableHeader> = useMemo(
+    () => [
+      { key: 'billId', header: t('billId', 'Bill ID') },
+      { key: 'transactionType', header: t('transactionType', 'Type') },
+      { key: 'status', header: t('status', 'Status') },
+      { key: 'traderInvoiceNumber', header: t('traderInvoiceNumber', 'Trader invoice') },
+      { key: 'kraInvoiceNumber', header: t('kraInvoiceNumber', 'KRA invoice') },
+      { key: 'attemptCount', header: t('attemptCount', 'Attempts') },
+      { key: 'dateCreated', header: t('dateCreated', 'Date created') },
+      { key: 'confirmedAt', header: t('confirmedAt', 'Confirmed at') },
+    ],
+    [t],
+  );
+
+  const tableRows: Array<TransactionRow> = useMemo(
+    () =>
+      pagedTransactions.map((transaction, index) => ({
+        id: transaction.uuid ?? `transaction-${index}`,
+        billId: displayValue(transaction.billId),
+        transactionType: displayValue(transaction.transactionType),
+        status: displayValue(transaction.status),
+        traderInvoiceNumber: displayValue(transaction.traderInvoiceNumber),
+        kraInvoiceNumber: displayValue(transaction.kraInvoiceNumber),
+        resultMessage: displayValue(transaction.resultMessage),
+        attemptCount: displayValue(transaction.attemptCount),
+        dateCreated: formatNullableDatetime(transaction.dateCreated),
+        confirmedAt: formatNullableDatetime(transaction.confirmedAt),
+      })),
+    [pagedTransactions],
+  );
+
+  const openDetails = useCallback((transaction: EtimsTransaction) => {
+    launchWorkspace2('etims-transaction-details', { transaction });
+  }, []);
+
+  const openConfirmActionModal = useCallback(
+    (action: 'retry' | 'reconcile' | 'reactivate', transaction: EtimsTransaction) => {
+      const dispose = showModal('etims-confirm-transaction-action-modal', {
+        close: () => dispose(),
+        action,
+        uuid: transaction.uuid,
+        displayName: transactionLabel(transaction),
+        onComplete: () => mutate(),
+      });
+    },
+    [mutate],
+  );
+
+  const openOverrideModal = useCallback(
+    (transaction: EtimsTransaction) => {
+      const dispose = showModal('etims-override-reconciliation-modal', {
+        close: () => dispose(),
+        uuid: transaction.uuid,
+        displayName: transactionLabel(transaction),
+        kraInvoiceNumber: transaction.kraInvoiceNumber,
+        onComplete: () => mutate(),
+      });
+    },
+    [mutate],
+  );
+
+  const handleDownloadTaxInvoice = useCallback(
+    async (transaction: EtimsTransaction) => {
+      if (!transaction.billId) {
+        showSnackbar({
+          kind: 'error',
+          title: t('taxInvoiceError', 'Unable to download tax invoice'),
+          subtitle: t('missingBillId', 'This transaction has no bill ID'),
+        });
+        return;
+      }
+
+      setIsDownloading(transaction.uuid);
+      try {
+        await downloadEtimsTaxInvoice(transaction.billId);
+        showSnackbar({
+          kind: 'success',
+          title: t('taxInvoiceDownloaded', 'Tax invoice downloaded'),
+        });
+      } catch (downloadError: any) {
+        showSnackbar({
+          kind: 'error',
+          title: t('taxInvoiceError', 'Unable to download tax invoice'),
+          subtitle: downloadError?.message,
+        });
+      } finally {
+        setIsDownloading(null);
+      }
+    },
+    [t],
+  );
+
+  const handleSearchChange = useCallback((event: React.ChangeEvent<HTMLInputElement> | '', value?: string) => {
+    setSearchTerm(typeof event === 'string' ? value ?? '' : event.target.value);
+    setPage(1);
+  }, []);
+
+  const handlePaginationChange = useCallback(
+    ({ page: nextPage, pageSize: nextSize }: { page: number; pageSize: number }) => {
+      if (nextSize !== pageSize) {
+        setPageSize(nextSize);
+      }
+      setPage(nextPage);
+    },
+    [pageSize],
+  );
+
+  if (isLoading) {
+    return (
+      <div className={styles.container}>
+        <DataTableSkeleton headers={headers} rowCount={5} showHeader showToolbar />
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className={styles.dataTableContainer}>
+        <ErrorCard error={error} headerTitle={t('transactionsError', 'Transactions')} />
+      </div>
+    );
+  }
+
+  return (
+    <div className={styles.container}>
+      <DataTable rows={tableRows} headers={headers} size="sm" useZebraStyles isSortable>
+        {({
+          rows,
+          headers: tableHeaders,
+          getHeaderProps,
+          getRowProps,
+          getToolbarProps,
+          getTableProps,
+          getTableContainerProps,
+        }) => (
+          <TableContainer
+            title={t('transactions', 'Transactions')}
+            description={t(
+              'transactionsDescription',
+              'Review the fiscal outbox, retry failed submissions, and reconcile ambiguous KRA results.',
+            )}
+            {...getTableContainerProps()}>
+            <TableToolbar {...getToolbarProps()}>
+              <TableToolbarContent>
+                <TableToolbarSearch
+                  persistent
+                  onChange={handleSearchChange}
+                  placeholder={t('searchTransactions', 'Search by bill ID, invoice, or result')}
+                />
+                <Dropdown
+                  size="sm"
+                  id="transaction-status-filter"
+                  className={styles.statusFilter}
+                  label={t('status', 'Status')}
+                  titleText=""
+                  items={statusItems}
+                  itemToString={(item) => item?.label ?? ''}
+                  selectedItem={statusItems.find((item) => item.id === statusFilter)}
+                  onChange={({ selectedItem }) => {
+                    setStatusFilter((selectedItem?.id as StatusFilter) ?? 'ALL');
+                    setPage(1);
+                  }}
+                />
+              </TableToolbarContent>
+            </TableToolbar>
+
+            <Table {...getTableProps()} aria-label={t('transactions', 'Transactions')}>
+              <TableHead>
+                <TableRow>
+                  {tableHeaders.map((header) => (
+                    <TableHeader {...getHeaderProps({ header })}>{header.header}</TableHeader>
+                  ))}
+                  <TableHeader aria-label={t('rowActions', 'Row actions')} />
+                </TableRow>
+              </TableHead>
+              <TableBody>
+                {rows.map((row) => {
+                  const transaction = pagedTransactions.find((item) => item.uuid === row.id);
+
+                  if (!transaction) {
+                    return null;
+                  }
+
+                  return (
+                    <TableRow {...getRowProps({ row })}>
+                      {row.cells.map((cell) => {
+                        if (cell.info.header === 'status') {
+                          return (
+                            <TableCell key={cell.id}>
+                              <Tag type={statusTagType(cell.value)} size="sm">
+                                {cell.value}
+                              </Tag>
+                            </TableCell>
+                          );
+                        }
+
+                        return <TableCell key={cell.id}>{cell.value}</TableCell>;
+                      })}
+                      <TableCell className="cds--table-column-menu">
+                        <OverflowMenu flipped size="sm" aria-label={t('rowActions', 'Row actions')}>
+                          <OverflowMenuItem
+                            itemText={t('viewDetails', 'View details')}
+                            onClick={() => openDetails(transaction)}
+                          />
+                          {isRetryable(transaction.status) ? (
+                            <UserHasAccess privilege="Retry eTIMS Transactions">
+                              <OverflowMenuItem
+                                itemText={t('retrySubmission', 'Retry submission')}
+                                onClick={() => openConfirmActionModal('retry', transaction)}
+                              />
+                            </UserHasAccess>
+                          ) : null}
+                          {isReactivatable(transaction.status) ? (
+                            <UserHasAccess privilege="Retry eTIMS Transactions">
+                              <OverflowMenuItem
+                                itemText={t('retrySubmission', 'Retry submission')}
+                                onClick={() => openConfirmActionModal('reactivate', transaction)}
+                              />
+                            </UserHasAccess>
+                          ) : null}
+                          {isReconcilable(transaction.status) ? (
+                            <UserHasAccess privilege="Reconcile eTIMS Transactions">
+                              <OverflowMenuItem
+                                itemText={t('reconcileWithKra', 'Reconcile with KRA')}
+                                onClick={() => openConfirmActionModal('reconcile', transaction)}
+                              />
+                            </UserHasAccess>
+                          ) : null}
+                          {isReconcilable(transaction.status) ? (
+                            <UserHasAccess privilege="Reconcile eTIMS Transactions">
+                              <OverflowMenuItem
+                                itemText={t('recordOverride', 'Record override')}
+                                onClick={() => openOverrideModal(transaction)}
+                              />
+                            </UserHasAccess>
+                          ) : null}
+                          {isConfirmed(transaction.status) ? (
+                            <OverflowMenuItem
+                              disabled={isDownloading === transaction.uuid}
+                              itemText={
+                                isDownloading === transaction.uuid
+                                  ? t('downloading', 'Downloading...')
+                                  : t('downloadTaxInvoice', 'Download tax invoice')
+                              }
+                              onClick={() => handleDownloadTaxInvoice(transaction)}
+                            />
+                          ) : null}
+                        </OverflowMenu>
+                      </TableCell>
+                    </TableRow>
+                  );
+                })}
+              </TableBody>
+            </Table>
+          </TableContainer>
+        )}
+      </DataTable>
+      <Pagination
+        itemsPerPageText={t('itemsPerPage', 'Items per page:')}
+        forwardText={t('nextPage', 'Next page')}
+        backwardText={t('previousPage', 'Previous page')}
+        itemRangeText={(min, max, total) => t('minMaxItems', '{{min}}-{{max}} of {{total}} items', { min, max, total })}
+        pageRangeText={(_current, total) => t('pageRangeText', 'of {{count}} pages', { count: total })}
+        page={page}
+        pageSize={pageSize}
+        pageSizes={pageSizes?.length > 0 ? pageSizes : PAGE_SIZE_OPTIONS}
+        totalItems={filteredTransactions.length}
+        onChange={handlePaginationChange}
+      />
+    </div>
+  );
+};
+
+export default EtimsTransactionTable;

package/src/transaction/etims-transaction-table.scss

@@ -0,0 +1,20 @@
+@use '@carbon/layout';
+@use '@carbon/colors';
+
+.dataTableContainer {
+  height: 100%;
+  margin: layout.$layout-01;
+}
+
+.container {
+  margin: 0;
+  border: 1px solid colors.$gray-20;
+
+  :global(.cds--table-toolbar) {
+    position: relative !important;
+  }
+}
+
+.statusFilter {
+  min-width: 16rem;
+}

package/src/transaction/etims-transaction.resource.ts

@@ -0,0 +1,180 @@
+import { type FetchResponse, openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import useSWR from 'swr';
+import type {
+  EtimsReconciliationOverride,
+  EtimsReconciliationOverridePayload,
+  EtimsTransaction,
+  EtimsTransactionStatus,
+  EtimsTransactionSummary,
+} from './etims-transaction.types';
+
+export const etimsTransactionUrl = `${restBaseUrl}/cashier/etimsTransaction`;
+export const etimsTaxInvoiceUrl = `${restBaseUrl}/cashier/etimsTaxInvoice`;
+
+export const RETRYABLE_STATUSES: Array<EtimsTransactionStatus> = ['PENDING', 'RETRY'];
+export const RECONCILABLE_STATUSES: Array<EtimsTransactionStatus> = ['RECONCILIATION_REQUIRED'];
+export const REACTIVATABLE_STATUSES: Array<EtimsTransactionStatus> = ['ACTION_REQUIRED'];
+
+type TransactionListResponse = { results: Array<EtimsTransaction> };
+
+const extractErrorMessage = async (response: FetchResponse, fallback: string) => {
+  const payload =
+    (response.data as { error?: string | { message?: string; detail?: string } } | undefined) ??
+    (await response.json().catch(() => ({})));
+  if (typeof payload?.error === 'string' && payload.error.trim()) {
+    return payload.error;
+  }
+
+  if (payload?.error && typeof payload.error === 'object') {
+    return payload.error.message ?? payload.error.detail ?? fallback;
+  }
+
+  if (typeof payload === 'string' && payload.trim()) {
+    return payload;
+  }
+
+  return fallback;
+};
+
+const requireOk = async <T>(response: FetchResponse<T>, fallback: string) => {
+  if (!response.ok) {
+    throw new Error(await extractErrorMessage(response, fallback));
+  }
+
+  return response.data;
+};
+
+export type TransactionListFilters = {
+  status?: EtimsTransactionStatus | 'ALL';
+  billId?: string;
+};
+
+export function useEtimsTransactions(filters: TransactionListFilters = {}) {
+  const params = new URLSearchParams({ v: 'default', limit: '100' });
+  const billId = filters.billId?.trim();
+  const status = filters.status && filters.status !== 'ALL' ? filters.status : undefined;
+
+  if (billId) {
+    params.set('q', billId);
+    params.set('billId', billId);
+  } else if (status) {
+    params.set('q', status);
+    params.set('status', status);
+  }
+
+  const { data, error, isLoading, isValidating, mutate } = useSWR<FetchResponse<TransactionListResponse>>(
+    `${etimsTransactionUrl}?${params.toString()}`,
+    openmrsFetch,
+  );
+
+  return {
+    transactions: data?.data?.results ?? [],
+    error,
+    isLoading,
+    isValidating,
+    mutate,
+  };
+}
+
+export function useEtimsTransaction(uuid?: string) {
+  const { data, error, isLoading, mutate } = useSWR<FetchResponse<EtimsTransaction>>(
+    uuid ? `${etimsTransactionUrl}/${uuid}?v=full` : null,
+    openmrsFetch,
+  );
+
+  return {
+    transaction: data?.data ?? null,
+    error,
+    isLoading,
+    mutate,
+  };
+}
+
+export function useEtimsReconciliationOverrides(uuid?: string) {
+  const { data, error, isLoading, mutate } = useSWR<FetchResponse<Array<EtimsReconciliationOverride>>>(
+    uuid ? `${etimsTransactionUrl}/${uuid}/reconciliationOverride` : null,
+    openmrsFetch,
+  );
+
+  return {
+    overrides: data?.data ?? [],
+    error,
+    isLoading,
+    mutate,
+  };
+}
+
+export async function retryEtimsTransaction(uuid: string) {
+  const response = await openmrsFetch<EtimsTransactionSummary>(`${etimsTransactionUrl}/${uuid}/retry`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({}),
+  });
+
+  return requireOk(response, 'Failed to retry eTIMS transaction');
+}
+
+export async function reactivateEtimsTransaction(uuid: string) {
+  const response = await openmrsFetch<EtimsTransactionSummary>(`${etimsTransactionUrl}/${uuid}/reactivate`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({}),
+  });
+
+  return requireOk(response, 'Failed to reactivate eTIMS transaction');
+}
+
+export async function reconcileEtimsTransaction(uuid: string) {
+  const response = await openmrsFetch<EtimsTransactionSummary>(`${etimsTransactionUrl}/${uuid}/reconciliation`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({}),
+  });
+
+  return requireOk(response, 'Failed to reconcile eTIMS transaction');
+}
+
+export async function overrideEtimsReconciliation(uuid: string, payload: EtimsReconciliationOverridePayload) {
+  const response = await openmrsFetch<EtimsTransactionSummary>(
+    `${etimsTransactionUrl}/${uuid}/reconciliationOverride`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    },
+  );
+
+  return requireOk(response, 'Failed to record eTIMS reconciliation override');
+}
+
+export async function downloadEtimsTaxInvoice(billId: number) {
+  const response = await fetch(`${window.openmrsBase}${etimsTaxInvoiceUrl}?billId=${billId}`, {
+    credentials: 'same-origin',
+  });
+
+  if (!response.ok) {
+    const message = (await response.text()).trim();
+    throw new Error(message || 'Failed to download tax invoice');
+  }
+
+  const blob = await response.blob();
+  const objectUrl = URL.createObjectURL(blob);
+  const link = document.createElement('a');
+  link.href = objectUrl;
+  link.download = `tax-invoice-${billId}.pdf`;
+  document.body.appendChild(link);
+  link.click();
+  link.remove();
+  URL.revokeObjectURL(objectUrl);
+}
+
+export const isRetryable = (status?: EtimsTransactionStatus | null) =>
+  Boolean(status && RETRYABLE_STATUSES.includes(status));
+
+export const isReconcilable = (status?: EtimsTransactionStatus | null) =>
+  Boolean(status && RECONCILABLE_STATUSES.includes(status));
+
+export const isReactivatable = (status?: EtimsTransactionStatus | null) =>
+  Boolean(status && REACTIVATABLE_STATUSES.includes(status));
+
+export const isConfirmed = (status?: EtimsTransactionStatus | null) => status === 'CONFIRMED';