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

package/src/credit-note/etims-credit-note-table.component.tsx

@@ -0,0 +1,284 @@
+import React, { useCallback, useMemo, useState } from 'react';
+import {
+  Button,
+  DataTable,
+  DataTableSkeleton,
+  OverflowMenu,
+  OverflowMenuItem,
+  Pagination,
+  Table,
+  TableBody,
+  TableCell,
+  TableContainer,
+  TableHead,
+  TableHeader,
+  TableRow,
+  TableToolbar,
+  TableToolbarContent,
+  TableToolbarSearch,
+  Tag,
+  type DataTableHeader,
+} from '@carbon/react';
+import { Add } from '@carbon/react/icons';
+import {
+  ErrorCard,
+  formatDatetime,
+  launchWorkspace2,
+  parseDate,
+  useDebounce,
+  usePaginationInfo,
+  UserHasAccess,
+} from '@openmrs/esm-framework';
+import { useTranslation } from 'react-i18next';
+import type { EtimsTransaction } from '../transaction/etims-transaction.types';
+import { useEtimsCreditNotes } from './etims-credit-note.resource';
+import styles from './etims-credit-note-table.scss';
+
+const DEFAULT_PAGE_SIZE = 10;
+const PAGE_SIZE_OPTIONS = [10, 20, 50, 100];
+
+type CreditNoteRow = {
+  id: string;
+  billId: string;
+  status: string;
+  traderInvoiceNumber: string;
+  kraInvoiceNumber: string;
+  resultMessage: 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 EtimsCreditNoteTable: React.FC = () => {
+  const { t } = useTranslation();
+  const [page, setPage] = useState(1);
+  const [pageSize, setPageSize] = useState(DEFAULT_PAGE_SIZE);
+  const [searchTerm, setSearchTerm] = useState('');
+  const debouncedSearchTerm = useDebounce(searchTerm, 300);
+  const { creditNotes, error, isLoading, mutate } = useEtimsCreditNotes();
+
+  const filteredCreditNotes = useMemo(() => {
+    const query = debouncedSearchTerm.trim().toLowerCase();
+
+    if (!query) {
+      return creditNotes;
+    }
+
+    return creditNotes.filter((creditNote) =>
+      [
+        creditNote.billId,
+        creditNote.status,
+        creditNote.traderInvoiceNumber,
+        creditNote.kraInvoiceNumber,
+        creditNote.cuInvoiceNumber,
+        creditNote.resultMessage,
+      ].some((value) => displayValue(value).toLowerCase().includes(query)),
+    );
+  }, [creditNotes, debouncedSearchTerm]);
+
+  const pagedCreditNotes = useMemo(() => {
+    const start = (page - 1) * pageSize;
+    return filteredCreditNotes.slice(start, start + pageSize);
+  }, [filteredCreditNotes, page, pageSize]);
+
+  const { pageSizes } = usePaginationInfo(DEFAULT_PAGE_SIZE, filteredCreditNotes.length, page, pagedCreditNotes.length);
+
+  const headers: Array<DataTableHeader> = useMemo(
+    () => [
+      { key: 'billId', header: t('billId', 'Bill ID') },
+      { key: 'status', header: t('status', 'Status') },
+      { key: 'traderInvoiceNumber', header: t('traderInvoiceNumber', 'Trader invoice') },
+      { key: 'kraInvoiceNumber', header: t('kraInvoiceNumber', 'KRA invoice') },
+      { key: 'resultMessage', header: t('resultMessage', 'Last result') },
+      { key: 'dateCreated', header: t('dateCreated', 'Date created') },
+      { key: 'confirmedAt', header: t('confirmedAt', 'Confirmed at') },
+    ],
+    [t],
+  );
+
+  const tableRows: Array<CreditNoteRow> = useMemo(
+    () =>
+      pagedCreditNotes.map((creditNote, index) => ({
+        id: creditNote.uuid ?? `credit-note-${index}`,
+        billId: displayValue(creditNote.billId),
+        status: displayValue(creditNote.status),
+        traderInvoiceNumber: displayValue(creditNote.traderInvoiceNumber),
+        kraInvoiceNumber: displayValue(creditNote.kraInvoiceNumber),
+        resultMessage: displayValue(creditNote.resultMessage),
+        dateCreated: formatNullableDatetime(creditNote.dateCreated),
+        confirmedAt: formatNullableDatetime(creditNote.confirmedAt),
+      })),
+    [pagedCreditNotes],
+  );
+
+  const openCreateWorkspace = useCallback(() => {
+    launchWorkspace2('etims-credit-note-form', { mutateCreditNotes: mutate });
+  }, [mutate]);
+
+  const openDetails = useCallback((transaction: EtimsTransaction) => {
+    launchWorkspace2('etims-transaction-details', { transaction });
+  }, []);
+
+  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('creditNotes', 'Credit notes')} />
+      </div>
+    );
+  }
+
+  return (
+    <div className={styles.container}>
+      <DataTable rows={tableRows} headers={headers} size="sm" useZebraStyles isSortable>
+        {({ rows, headers: tableHeaders, getHeaderProps, getRowProps, getTableProps, getTableContainerProps }) => (
+          <TableContainer
+            title={t('creditNotes', 'Credit notes')}
+            description={t(
+              'creditNotesDescription',
+              'Raise credit notes against confirmed eTIMS invoices and track their submission to KRA.',
+            )}
+            {...getTableContainerProps()}>
+            <TableToolbar>
+              <TableToolbarContent>
+                <TableToolbarSearch
+                  persistent
+                  onChange={handleSearchChange}
+                  placeholder={t('searchCreditNotes', 'Search by bill ID, invoice, or result')}
+                />
+                <UserHasAccess privilege="Create eTIMS Credit Notes">
+                  <Button kind="primary" size="sm" renderIcon={Add} onClick={openCreateWorkspace}>
+                    {t('createCreditNote', 'Create credit note')}
+                  </Button>
+                </UserHasAccess>
+              </TableToolbarContent>
+            </TableToolbar>
+
+            <Table {...getTableProps()} aria-label={t('creditNotes', 'Credit notes')}>
+              <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 creditNote = pagedCreditNotes.find((item) => item.uuid === row.id);
+
+                  if (!creditNote) {
+                    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(creditNote)}
+                          />
+                        </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={filteredCreditNotes.length}
+        onChange={handlePaginationChange}
+      />
+    </div>
+  );
+};
+
+export default EtimsCreditNoteTable;

package/src/credit-note/etims-credit-note-table.scss

@@ -0,0 +1,16 @@
+@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;
+  }
+}

package/src/credit-note/etims-credit-note.resource.ts

@@ -0,0 +1,96 @@
+import { type FetchResponse, openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import useSWR from 'swr';
+import { useEtimsTransactions } from '../transaction/etims-transaction.resource';
+import type { EtimsTransaction } from '../transaction/etims-transaction.types';
+import type { BillSearchResult, EtimsAmendmentPayload, EtimsAmendmentResult } from './etims-credit-note.types';
+
+export const etimsAmendmentUrl = `${restBaseUrl}/cashier/etimsAmendment`;
+export const cashierBillUrl = `${restBaseUrl}/cashier/bill`;
+
+const billSearchRep =
+  'custom:(uuid,id,display,receiptNumber,status,dateCreated,patient:(uuid,display),' +
+  'etims:(status,etimsInvoiceNumber,cuInvoiceNumber,qrUrl,receiptAvailable),' +
+  'lineItems:full)';
+
+type BillSearchResponse = { results: Array<BillSearchResult> };
+
+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;
+  }
+
+  return fallback;
+};
+
+/**
+ * Free-text search over cashier bills, scoped to the patient's names and identifiers, that also
+ * pulls the eTIMS fiscal state and line items required to enqueue a credit note.
+ */
+export function useBillSearch(query?: string) {
+  const trimmed = query?.trim();
+  const params = new URLSearchParams({ v: billSearchRep, includeVoided: 'true', limit: '20' });
+  if (trimmed) {
+    params.set('q', trimmed);
+  }
+
+  const { data, error, isLoading, isValidating } = useSWR<FetchResponse<BillSearchResponse>>(
+    trimmed ? `${cashierBillUrl}?${params.toString()}` : null,
+    openmrsFetch,
+  );
+
+  return {
+    bills: data?.data?.results ?? [],
+    error,
+    isLoading,
+    isValidating,
+  };
+}
+
+/**
+ * Lists eTIMS credit-note transactions. The transaction search endpoint filters by status or bill,
+ * so the credit-note subset is derived on the client from the full transaction list.
+ */
+export function useEtimsCreditNotes() {
+  const { transactions, error, isLoading, isValidating, mutate } = useEtimsTransactions({ status: 'ALL' });
+
+  const creditNotes = (transactions as Array<EtimsTransaction>).filter(
+    (transaction) => transaction.transactionType === 'CREDIT_NOTE',
+  );
+
+  return { creditNotes, error, isLoading, isValidating, mutate };
+}
+
+export async function createEtimsAmendment(payload: EtimsAmendmentPayload) {
+  const response = await openmrsFetch<EtimsAmendmentResult>(etimsAmendmentUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    throw new Error(await extractErrorMessage(response, 'Failed to enqueue credit note'));
+  }
+
+  return response.data;
+}
+
+/**
+ * Line item labels come back as "uuid:label" from the cashier REST layer; keep only the label.
+ */
+export const parseLineItemName = (value?: string | null) => {
+  if (!value) {
+    return '';
+  }
+
+  const separatorIndex = value.indexOf(':');
+  return separatorIndex === -1 ? value : value.slice(separatorIndex + 1);
+};
+
+export const hasConfirmedSale = (bill?: BillSearchResult | null) => bill?.etims?.status === 'CONFIRMED';

package/src/credit-note/etims-credit-note.types.ts

@@ -0,0 +1,56 @@
+import type { EtimsTransactionStatus, EtimsTransactionType } from '../transaction/etims-transaction.types';
+
+export type EtimsAmendmentType = 'FULL_CREDIT' | 'PARTIAL_CREDIT' | 'REPLACEMENT';
+
+export interface EtimsAmendmentPayload {
+  type: EtimsAmendmentType;
+  billUuid: string;
+  reason?: string;
+  billLineItemUuid?: string;
+  creditNoteUuid?: string;
+}
+
+export interface EtimsAmendmentResult {
+  uuid: string;
+  billId?: number | null;
+  transactionType?: EtimsTransactionType | null;
+  status?: EtimsTransactionStatus | null;
+  kraInvoiceNumber?: string | null;
+  traderInvoiceNumber?: string | null;
+  resultCode?: string | null;
+  resultMessage?: string | null;
+  cuInvoiceNumber?: string | null;
+  receiptNumber?: string | null;
+  confirmedAt?: string | null;
+}
+
+export interface BillEtimsState {
+  status?: EtimsTransactionStatus | null;
+  etimsInvoiceNumber?: string | null;
+  cuInvoiceNumber?: string | null;
+  qrUrl?: string | null;
+  receiptAvailable?: boolean | null;
+}
+
+export interface BillLineItem {
+  uuid: string;
+  display?: string | null;
+  item?: string | null;
+  billableService?: string | null;
+  quantity?: number | null;
+  price?: number | null;
+  paymentStatus?: string | null;
+  voided?: boolean | null;
+}
+
+export interface BillSearchResult {
+  uuid: string;
+  id?: number | null;
+  display?: string | null;
+  receiptNumber?: string | null;
+  status?: string | null;
+  dateCreated?: string | null;
+  patient?: { uuid: string; display: string } | null;
+  etims?: BillEtimsState | null;
+  lineItems?: Array<BillLineItem> | null;
+}

package/src/credit-note/etims-credit-note.workspace.scss

@@ -0,0 +1,76 @@
+@use '@carbon/colors';
+@use '@carbon/layout';
+@use '@carbon/type';
+
+.form {
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+  height: 100%;
+}
+
+.formContainer {
+  margin: layout.$spacing-05;
+  display: flex;
+  flex-direction: column;
+  justify-content: flex-start;
+  gap: layout.$spacing-05;
+}
+
+.searchField {
+  display: flex;
+  flex-direction: column;
+}
+
+.searchStatus {
+  min-height: layout.$spacing-05;
+  margin-top: layout.$spacing-02;
+}
+
+.billSummary {
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-03;
+  padding: layout.$spacing-05;
+  background-color: colors.$gray-10;
+  border-radius: layout.$spacing-02;
+}
+
+.summaryRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: layout.$spacing-03;
+}
+
+.summaryLabel {
+  @include type.type-style('label-01');
+  color: colors.$gray-70;
+}
+
+.tablet {
+  padding: layout.$spacing-06 layout.$spacing-05;
+  background-color: colors.$white;
+
+  & button {
+    max-width: 50% !important;
+  }
+}
+
+.desktop {
+  padding: 0;
+
+  & button {
+    max-width: 50% !important;
+  }
+}
+
+.buttonContainer {
+  max-width: 50%;
+}
+
+.inlineLoading {
+  display: flex;
+  align-items: center;
+  gap: layout.$spacing-03;
+}