@openmrs/esm-billing-app 1.1.2-pre.8 → 1.2.0

package/src/refunds/request-refund.modal.tsx

@@ -0,0 +1,218 @@
+import React, { useState } from 'react';
+import {
+  Button,
+  InlineLoading,
+  ModalBody,
+  ModalFooter,
+  ModalHeader,
+  NumberInput,
+  Stack,
+  TextArea,
+} from '@carbon/react';
+import { useTranslation } from 'react-i18next';
+import { getCoreTranslation, showSnackbar, useConfig } from '@openmrs/esm-framework';
+import type { BillingConfig } from '../config-schema';
+import { convertToCurrency } from '../helpers';
+import { requestRefund } from './refunds.resource';
+import styles from './request-refund.modal.scss';
+
+interface Props {
+  closeModal: () => void;
+  bill: {
+    uuid: string;
+    total: number;
+    amountAfterDiscount: number;
+    receiptNumber?: string;
+    lineItemCount?: number;
+  };
+  lineItem?: {
+    uuid: string;
+    display: string;
+    total: number;
+    quantity?: number;
+    price?: number;
+  };
+  remainingRefundable: number;
+  onMutate?: () => void;
+}
+
+const RequestRefundModal: React.FC<Props> = ({ closeModal, bill, lineItem, remainingRefundable, onMutate }) => {
+  const { t } = useTranslation();
+  const { defaultCurrency } = useConfig<BillingConfig>();
+  const [amount, setAmount] = useState<number | null>(null);
+  const [reason, setReason] = useState('');
+  const [submitting, setSubmitting] = useState(false);
+
+  const isLineItem = !!lineItem;
+  const scopeTotal = lineItem?.total ?? bill.total;
+  const alreadyRefunded = isLineItem
+    ? scopeTotal - remainingRefundable
+    : bill.amountAfterDiscount - remainingRefundable;
+  const trimmedReason = reason.trim();
+
+  const reasonError = reason.length > 1000 ? t('reasonTooLong', 'Reason cannot exceed 1000 characters') : null;
+
+  const amountError = (() => {
+    if (amount == null || Number.isNaN(amount)) return null;
+    if (remainingRefundable <= 0) return t('noRefundableAmount', 'No refundable amount remaining on this bill');
+    if (amount <= 0) return t('amountMustBePositive', 'Amount must be greater than 0');
+    if (amount > remainingRefundable)
+      return t('amountExceedsRefundable', 'Amount cannot exceed {{max}}', {
+        max: convertToCurrency(remainingRefundable, defaultCurrency),
+      });
+    return null;
+  })();
+
+  const canSubmit =
+    !submitting && amount != null && amount > 0 && trimmedReason.length > 0 && !reasonError && !amountError;
+
+  const handleSubmit = async () => {
+    if (!canSubmit || amount == null) return;
+    setSubmitting(true);
+    try {
+      await requestRefund({
+        bill: bill.uuid,
+        lineItem: lineItem?.uuid,
+        refundAmount: amount,
+        reason: trimmedReason,
+      });
+      onMutate?.();
+      showSnackbar({
+        title: t('refundRequested', 'Refund request submitted'),
+        subtitle: t('refundPendingReview', 'An admin will review your request'),
+        kind: 'success',
+      });
+      closeModal();
+    } catch (err: unknown) {
+      const subtitle = (err as any)?.responseBody?.error?.message ?? (err instanceof Error ? err.message : undefined);
+      showSnackbar({
+        title: t('refundRequestFailed', 'Could not submit refund request'),
+        subtitle,
+        kind: 'error',
+      });
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <>
+      <ModalHeader closeModal={closeModal} title={t('requestRefund', 'Request refund')} />
+      <ModalBody className={styles.modalBody}>
+        <Stack gap={5}>
+          <section className={styles.scopePanel} aria-label={t('refundScope', 'Refund scope')}>
+            <div className={styles.scopePrimary}>
+              {isLineItem ? lineItem.display : t('wholeBillScope', 'Whole bill')}
+            </div>
+            <ul className={styles.scopeMeta}>
+              {bill.receiptNumber && <li>{t('invoiceLabel', 'Invoice {{number}}', { number: bill.receiptNumber })}</li>}
+              {isLineItem && lineItem.quantity != null && lineItem.price != null && (
+                <li>
+                  {t('qtyTimesPrice', 'Qty {{quantity}} × {{price}}', {
+                    quantity: lineItem.quantity,
+                    price: convertToCurrency(lineItem.price, defaultCurrency),
+                  })}
+                </li>
+              )}
+              {!isLineItem && bill.lineItemCount != null && (
+                <li>{t('lineItemCount', '{{count}} line items', { count: bill.lineItemCount })}</li>
+              )}
+              <li className={styles.scopeTotal}>
+                {isLineItem
+                  ? t('lineTotalLabel', 'Line total {{total}}', {
+                      total: convertToCurrency(scopeTotal, defaultCurrency),
+                    })
+                  : t('billTotalLabel', 'Bill total {{total}}', {
+                      total: convertToCurrency(scopeTotal, defaultCurrency),
+                    })}
+              </li>
+            </ul>
+          </section>
+
+          <NumberInput
+            id="refund-amount"
+            label={t('refundAmountLabel', 'Refund amount ({{currency}})', { currency: defaultCurrency })}
+            allowEmpty
+            min={0}
+            max={remainingRefundable}
+            value={amount ?? ''}
+            invalid={!!amountError}
+            invalidText={amountError ?? ''}
+            onChange={(_e, { value: v }) => {
+              if (v === '' || v == null) {
+                setAmount(null);
+                return;
+              }
+              const n = typeof v === 'string' ? Number.parseFloat(v) : v;
+              setAmount(Number.isNaN(n) ? null : n);
+            }}
+          />
+
+          {amount != null && amount > 0 && !amountError && (
+            <section className={styles.summaryCard} aria-label={t('refundSummary', 'Refund summary')}>
+              <span className={styles.summaryLabel}>
+                {isLineItem ? t('lineTotal', 'Line total') : t('billTotal', 'Bill total')}
+              </span>
+              <span className={styles.summaryValue}>
+                {convertToCurrency(isLineItem ? scopeTotal : bill.amountAfterDiscount, defaultCurrency)}
+              </span>
+
+              {alreadyRefunded > 0 && (
+                <>
+                  <span className={styles.summaryLabel}>{t('alreadyRefunded', 'Already refunded')}</span>
+                  <span className={`${styles.summaryValue} ${styles.summaryRefund}`}>
+                    −{convertToCurrency(alreadyRefunded, defaultCurrency)}
+                  </span>
+                </>
+              )}
+
+              <span className={styles.summaryLabel}>{t('refundAmount', 'Refund amount')}</span>
+              <span className={`${styles.summaryValue} ${styles.summaryRefund}`}>
+                −{convertToCurrency(amount, defaultCurrency)}
+              </span>
+
+              <span className={styles.summaryDivider} aria-hidden="true" />
+
+              <span className={styles.summaryTotalLabel}>{t('amountAfterRefund', 'Amount after refund')}</span>
+              <span className={styles.summaryTotalValue}>
+                {convertToCurrency(remainingRefundable - amount, defaultCurrency)}
+              </span>
+            </section>
+          )}
+
+          <TextArea
+            id="refund-reason"
+            labelText={t('reason', 'Reason')}
+            placeholder={
+              isLineItem
+                ? t('lineItemReasonPlaceholder', 'e.g., duplicate charge, wrong item billed')
+                : t('billReasonPlaceholder', 'e.g., payment made in error, duplicate payment')
+            }
+            maxCount={1000}
+            enableCounter
+            required
+            rows={3}
+            value={reason}
+            invalid={!!reasonError}
+            invalidText={reasonError ?? ''}
+            onChange={(e) => setReason(e.target.value)}
+          />
+        </Stack>
+      </ModalBody>
+      <ModalFooter>
+        <Button kind="secondary" onClick={closeModal}>
+          {getCoreTranslation('cancel')}
+        </Button>
+        <Button kind="primary" onClick={handleSubmit} disabled={!canSubmit}>
+          {submitting ? (
+            <InlineLoading description={t('submitting', 'Submitting') + '...'} />
+          ) : (
+            <span>{t('submitRequest', 'Submit request')}</span>
+          )}
+        </Button>
+      </ModalFooter>
+    </>
+  );
+};
+
+export default RequestRefundModal;

package/src/routes.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.openmrs.org/routes.schema.json",
   "backendDependencies": {
-    "billing": ">=2.0.0",
+    "billing": ">=2.3.0-0",
     "webservices.rest": ">=2.24.0"
   },
   "pages": [
@@ -35,6 +35,14 @@
         "columnSpan": 4
       }
     },
+    {
+      "name": "visit-bills-panel",
+      "component": "visitBillsPanel",
+      "slot": "visit-summary-panels",
+      "meta": {
+        "title": "Bills"
+      }
+    },
     {
       "name": "billing-summary-dashboard-link",
       "component": "billingSummaryDashboardLink",
@@ -71,6 +79,12 @@
       "slot": "patient-banner-tags-slot",
       "order": 2
     },
+    {
+      "name": "patient-banner-payment-status-tag",
+      "component": "patientPaymentStatusTag",
+      "slot": "patient-banner-tags-slot",
+      "order": 3
+    },
     {
       "name": "billable-services-left-panel-link",
       "component": "billableServicesLeftPanelLink",
@@ -82,6 +96,18 @@
       "component": "billingSettingsLeftPanelMenu",
       "slot": "billable-services-left-panel-slot",
       "order": 1
+    },
+    {
+      "name": "discount-requests-left-panel-link",
+      "component": "discountRequestsLeftPanelLink",
+      "slot": "billable-services-left-panel-slot",
+      "order": 2
+    },
+    {
+      "name": "refund-requests-left-panel-link",
+      "component": "refundRequestsLeftPanelLink",
+      "slot": "billable-services-left-panel-slot",
+      "order": 3
     }
   ],
   "modals": [
@@ -116,7 +142,15 @@
     {
       "name": "finalize-bill-confirmation-modal",
       "component": "finalizeBillConfirmationModal"
-    }
+    },
+    {
+      "name": "delete-bill-confirmation-modal",
+      "component": "deleteBillConfirmationModal"
+    },
+    { "name": "request-discount-modal", "component": "requestDiscountModal" },
+    { "name": "review-bill-discounts-modal", "component": "reviewBillDiscountsModal" },
+    { "name": "request-refund-modal", "component": "requestRefundModal" },
+    { "name": "review-bill-refunds-modal", "component": "reviewBillRefundsModal" }
   ],
   "workspaces2": [
     {

package/src/types/index.ts

@@ -5,10 +5,26 @@ export const BillStatus = {
   POSTED: 'POSTED',
   PAID: 'PAID',
   ADJUSTED: 'ADJUSTED',
+  PARTIALLY_REFUNDED: 'PARTIALLY_REFUNDED',
+  REFUNDED: 'REFUNDED',
+  REFUND_REQUESTED: 'REFUND_REQUESTED',
 } as const;
 
 export type BillStatus = (typeof BillStatus)[keyof typeof BillStatus];
 
+export const BillLineItemStatus = {
+  PENDING: 'PENDING',
+  PAID: 'PAID',
+  CANCELLED: 'CANCELLED',
+  ADJUSTED: 'ADJUSTED',
+  EXEMPTED: 'EXEMPTED',
+  REFUND_REQUESTED: 'REFUND_REQUESTED',
+  REFUNDED: 'REFUNDED',
+  PARTIALLY_REFUNDED: 'PARTIALLY_REFUNDED',
+} as const;
+
+export type BillLineItemStatus = (typeof BillLineItemStatus)[keyof typeof BillLineItemStatus];
+
 export interface MappedBill {
   uuid: string;
   id: number;
@@ -25,9 +41,13 @@ export interface MappedBill {
   lineItems: Array<LineItem>;
   billingService: string;
   payments: Array<Payment>;
+  discounts?: Array<BillDiscount>;
+  refunds?: Array<BillRefund>;
   totalAmount?: number;
+  netAmount: number;
   tenderedAmount?: number;
   display?: string;
+  visitUuid?: string;
 }
 
 interface LocationLink {
@@ -65,7 +85,7 @@ interface Provider {
 export interface LineItem {
   uuid?: string;
   item?: string;
-  paymentStatus: string;
+  status: BillLineItemStatus;
   billableService?: string;
   quantity: number;
   price: number;
@@ -157,7 +177,12 @@ export interface PatientInvoice {
   status: string;
   adjustmentReason: string | null;
   id: number;
+  visit?: { uuid: string; display: string };
   resourceVersion: string;
+  total: number;
+  amountAfterDiscount: number;
+  discounts: BillDiscount[];
+  refunds: BillRefund[];
 }
 
 export interface PatientDetails {
@@ -230,6 +255,7 @@ export type CreateBillPayload = {
   payments: Array<PaymentPayload>;
   patient: string;
   status: string;
+  visit?: string;
 };
 
 export type UpdateBillPayload = {
@@ -261,3 +287,92 @@ export type PaymentModePayload = {
   name: string;
   description: string;
 };
+
+export const BillDiscountStatus = {
+  PENDING: 'PENDING',
+  APPROVED: 'APPROVED',
+  REJECTED: 'REJECTED',
+} as const;
+
+export type BillDiscountStatus = (typeof BillDiscountStatus)[keyof typeof BillDiscountStatus];
+
+export const BillDiscountType = {
+  PERCENTAGE: 'PERCENTAGE',
+  FIXED_AMOUNT: 'FIXED_AMOUNT',
+} as const;
+
+export type BillDiscountType = (typeof BillDiscountType)[keyof typeof BillDiscountType];
+
+export interface UserRef {
+  uuid: string;
+  display: string;
+}
+
+export interface BillDiscount {
+  uuid: string;
+  billUuid: string;
+  lineItemUuid: string | null;
+  discountType: BillDiscountType;
+  discountValue: number;
+  discountAmount: number;
+  justification: string;
+  initiator: UserRef;
+  approver: UserRef | null;
+  dateCreated: string;
+  status: BillDiscountStatus;
+  voided: boolean;
+}
+
+export interface RequestDiscountPayload {
+  bill: string;
+  lineItem?: string;
+  discountType: BillDiscountType;
+  discountValue: number;
+  justification: string;
+}
+
+export interface DecideDiscountPayload {
+  status: Exclude<BillDiscountStatus, 'PENDING'>;
+  approver: string;
+}
+
+export interface PatientPaymentStatus {
+  status: 'PAID' | 'UNPAID' | 'UNKNOWN';
+  reason: string;
+}
+export const RefundStatus = {
+  REQUESTED: 'REQUESTED',
+  APPROVED: 'APPROVED',
+  REJECTED: 'REJECTED',
+  COMPLETED: 'COMPLETED',
+} as const;
+export type RefundStatus = (typeof RefundStatus)[keyof typeof RefundStatus];
+
+export interface BillRefund {
+  uuid: string;
+  billUuid: string;
+  lineItemUuid: string | null;
+  refundAmount: number;
+  reason: string;
+  initiator: UserRef;
+  approver: UserRef | null;
+  completer: UserRef | null;
+  dateApproved: string | null;
+  dateCompleted: string | null;
+  dateCreated: string;
+  status: RefundStatus;
+  voided: boolean;
+}
+
+export interface RequestRefundPayload {
+  bill: string;
+  lineItem?: string;
+  refundAmount: number;
+  reason: string;
+}
+
+export interface DecideRefundPayload {
+  status: Exclude<RefundStatus, 'REQUESTED'>;
+  approver?: string;
+  completer?: string;
+}

package/src/visit-bills/visit-bills-panel.component.tsx

@@ -0,0 +1,151 @@
+import React, { useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+import {
+  DataTable,
+  DataTableSkeleton,
+  InlineNotification,
+  Layer,
+  Table,
+  TableBody,
+  TableCell,
+  TableContainer,
+  TableExpandedRow,
+  TableExpandHeader,
+  TableExpandRow,
+  TableHead,
+  TableHeader,
+  TableRow,
+  Tile,
+} from '@carbon/react';
+import { EmptyCardIllustration, ErrorState, formatDate, parseDate, useConfig } from '@openmrs/esm-framework';
+import { useBills } from '../billing.resource';
+import { convertToCurrency } from '../helpers';
+import InvoiceTable from '../invoice/invoice-table.component';
+import type { BillingConfig } from '../config-schema';
+import styles from './visit-bills-panel.scss';
+
+interface VisitBillsPanelProps {
+  visit: { uuid: string };
+  patientUuid: string;
+}
+
+const VisitBillsPanel: React.FC<VisitBillsPanelProps> = ({ visit, patientUuid }) => {
+  const { t } = useTranslation();
+  const { defaultCurrency } = useConfig<BillingConfig>();
+  const { bills, error, isLoading, isValidating, mutate } = useBills(patientUuid, undefined, visit.uuid);
+  const billsByUuid = useMemo(() => new Map(bills?.map((bill) => [bill.uuid, bill])), [bills]);
+
+  const headerData = [
+    { header: t('billDate', 'Bill date'), key: 'billDate' },
+    { header: t('invoiceNumber', 'Invoice number'), key: 'invoiceNumber' },
+    { header: t('billedItems', 'Billed items'), key: 'billedItems' },
+    { header: t('billTotal', 'Bill total'), key: 'billTotal' },
+  ];
+
+  const setBilledItems = (bill) =>
+    bill?.lineItems
+      ?.map((item) => item?.billableService || item?.item)
+      .filter(Boolean)
+      .join(' & ') || '--';
+
+  const formatBillDate = (dateCreated: string) => {
+    try {
+      return formatDate(parseDate(dateCreated), { mode: 'wide' });
+    } catch {
+      return '--';
+    }
+  };
+
+  const rowData = bills?.map((bill) => ({
+    id: bill.uuid,
+    billDate: bill.dateCreated ? formatBillDate(bill.dateCreated) : '--',
+    invoiceNumber: bill.receiptNumber,
+    billedItems: setBilledItems(bill),
+    billTotal: convertToCurrency(bill.totalAmount ?? 0, defaultCurrency),
+  }));
+
+  if (isLoading) {
+    return <DataTableSkeleton showHeader={false} showToolbar={false} zebra />;
+  }
+
+  if (error) {
+    return (
+      <Layer>
+        <ErrorState error={error} headerTitle={t('billList', 'Bill list')} />
+      </Layer>
+    );
+  }
+
+  if (!bills?.length) {
+    return (
+      <Layer className={styles.emptyStateContainer}>
+        <Tile className={styles.tile}>
+          <div className={styles.illo}>
+            <EmptyCardIllustration />
+          </div>
+          <p className={styles.content}>{t('noBillsToDisplay', 'There are no bills to display.')}</p>
+        </Tile>
+      </Layer>
+    );
+  }
+
+  return (
+    <DataTable isSortable rows={rowData} headers={headerData} size="md" useZebraStyles>
+      {({
+        getExpandHeaderProps,
+        getHeaderProps,
+        getRowProps,
+        getTableContainerProps,
+        getTableProps,
+        headers,
+        rows,
+      }) => (
+        <TableContainer {...getTableContainerProps()}>
+          <Table {...getTableProps()} aria-label={t('billList', 'Bill list')}>
+            <TableHead>
+              <TableRow>
+                <TableExpandHeader enableToggle {...getExpandHeaderProps()} />
+                {headers.map((header) => (
+                  <TableHeader key={header.key} {...getHeaderProps({ header })}>
+                    {header.header}
+                  </TableHeader>
+                ))}
+              </TableRow>
+            </TableHead>
+            <TableBody>
+              {rows.map((row) => {
+                const currentBill = billsByUuid.get(row.id);
+                return (
+                  <React.Fragment key={row.id}>
+                    <TableExpandRow {...getRowProps({ row })}>
+                      {row.cells.map((cell) => (
+                        <TableCell key={cell.id}>{cell.value}</TableCell>
+                      ))}
+                    </TableExpandRow>
+                    {row.isExpanded ? (
+                      <TableExpandedRow colSpan={headers.length + 1}>
+                        {currentBill ? (
+                          <InvoiceTable bill={currentBill} onMutate={mutate} isLoadingBill={isValidating} viewOnly />
+                        ) : (
+                          <InlineNotification
+                            kind="error"
+                            lowContrast
+                            title={t('billNotFound', 'Bill details could not be loaded')}
+                          />
+                        )}
+                      </TableExpandedRow>
+                    ) : (
+                      <TableExpandedRow className={styles.hiddenRow} colSpan={headers.length + 1} />
+                    )}
+                  </React.Fragment>
+                );
+              })}
+            </TableBody>
+          </Table>
+        </TableContainer>
+      )}
+    </DataTable>
+  );
+};
+
+export default VisitBillsPanel;

package/src/visit-bills/visit-bills-panel.scss

@@ -0,0 +1,31 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+.emptyStateContainer {
+  margin: layout.$spacing-03 0;
+}
+
+.hiddenRow {
+  display: none;
+}
+
+.illo {
+  margin-top: layout.$spacing-05;
+}
+
+.content {
+  @include type.type-style('heading-compact-01');
+  color: $text-02;
+  margin-top: layout.$spacing-05;
+  margin-bottom: layout.$spacing-03;
+}
+
+.tile {
+  text-align: center;
+  border: 1px solid $ui-03;
+}
+
+.menuItem {
+  max-width: none;
+}