@ampath/esm-dha-workflow-app 4.0.0-next.34 → 4.0.0-next.340

package/src/billing/dashboard/v2/cash-checklist/cash-checklist.resource.ts

@@ -0,0 +1,239 @@
+/**
+ * Cash payments — bills payable at the cash point before service.
+ *
+ * A bill stays OPEN while services keep adding line items. Each item can be paid
+ * in full or in part (never over its balance); every payment is recorded with a
+ * receipt. When there is no balance the bill can be CLOSED, which marks it Paid.
+ * Covers pure cash clients and the SHA copay slice a SHA patient settles in cash.
+ *
+ * DEMO STUB: in-memory store. Replace with the real cashier bill + line-item
+ * payment endpoints when wiring the backend.
+ */
+import { getClaimsByStatuses } from '../claims-accounting/claims-accounting.resource';
+import { splitBillForSha } from '../claims-accounting/bill-utils';
+
+export type BillSource = 'CASH' | 'SHA_COPAY';
+export type LineStatus = 'UNPAID' | 'PARTIAL' | 'PAID';
+export type BillStatus = 'OPEN' | 'PARTIAL' | 'SETTLED' | 'PAID';
+
+export interface BillLineItem {
+  id: string;
+  service: string; // Consultation, Laboratory, Pharmacy, Radiology…
+  code: string;
+  amount: number;
+  paidAmount: number;
+}
+
+export type PaymentMethod = 'M-Pesa' | 'SHA' | 'Cash';
+
+export interface PaymentEntry {
+  id: string;
+  itemId: string;
+  service: string;
+  amount: number;
+  method: PaymentMethod;
+  /** M-Pesa transaction reference (entered manually pre-integration). */
+  reference?: string;
+  receiptNo: string;
+  at: string;
+}
+
+export interface CashBill {
+  id: string;
+  billNo: string;
+  patientName: string;
+  crNumber: string;
+  locationUuid: string;
+  date: string; // yyyy-mm-dd
+  source: BillSource;
+  claimCode?: string;
+  closed: boolean;
+  lineItems: BillLineItem[];
+  payments: PaymentEntry[];
+}
+
+const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+const TODAY = new Date().toLocaleDateString('en-CA');
+
+let receiptSeq = 4100;
+const nextReceiptNo = () => `RCT-2026-${(receiptSeq += 1)}`;
+
+export const itemBalance = (i: BillLineItem) => i.amount - i.paidAmount;
+
+export function itemStatus(i: BillLineItem): LineStatus {
+  if (i.paidAmount <= 0) return 'UNPAID';
+  if (i.paidAmount >= i.amount) return 'PAID';
+  return 'PARTIAL';
+}
+
+export const billBalance = (b: CashBill) => b.lineItems.reduce((sum, i) => sum + itemBalance(i), 0);
+export const billPaid = (b: CashBill) => b.lineItems.reduce((sum, i) => sum + i.paidAmount, 0);
+export const billTotal = (b: CashBill) => b.lineItems.reduce((sum, i) => sum + i.amount, 0);
+
+export function billStatus(b: CashBill): BillStatus {
+  if (b.closed) return 'PAID';
+  if (billBalance(b) === 0) return 'SETTLED'; // fully paid, open — ready to close
+  if (billPaid(b) > 0) return 'PARTIAL';
+  return 'OPEN';
+}
+
+type CashBillSeed = Omit<CashBill, 'source'>;
+
+// SHA copays settled at the cash point this session (demo persistence).
+const copayState = new Map<string, { paidAmount: number; payments: PaymentEntry[]; closed: boolean }>();
+
+let CASH_BILLS: CashBillSeed[] = [
+  {
+    id: 'cb-1',
+    billNo: 'CASH-2026-0001',
+    patientName: 'James Otieno Onyango',
+    crNumber: 'CR4471290083321-5',
+    locationUuid: '',
+    date: TODAY,
+    closed: false,
+    lineItems: [
+      { id: 'cb-1-1', service: 'Consultation', code: 'SVC-CONS', amount: 500, paidAmount: 500 },
+      { id: 'cb-1-2', service: 'Laboratory · Full haemogram', code: 'LAB-CBC', amount: 800, paidAmount: 0 },
+      { id: 'cb-1-3', service: 'Pharmacy · Dispensing', code: 'PHA-DISP', amount: 350, paidAmount: 0 },
+    ],
+    payments: [
+      { id: 'p-cb-1-1', itemId: 'cb-1-1', service: 'Consultation', amount: 500, method: 'M-Pesa', reference: 'SFH3Q9K1AA', receiptNo: 'RCT-2026-4001', at: `${TODAY}T08:12:00` },
+    ],
+  },
+  {
+    id: 'cb-2',
+    billNo: 'CASH-2026-0002',
+    patientName: 'Mary Wanjiku Njoroge',
+    crNumber: 'CR9982130045567-1',
+    locationUuid: '',
+    date: TODAY,
+    closed: false,
+    lineItems: [
+      { id: 'cb-2-1', service: 'Consultation', code: 'SVC-CONS', amount: 500, paidAmount: 0 },
+      { id: 'cb-2-2', service: 'Radiology · Chest X-ray', code: 'RAD-CXR', amount: 1200, paidAmount: 0 },
+    ],
+    payments: [],
+  },
+  {
+    id: 'cb-3',
+    billNo: 'CASH-2026-0003',
+    patientName: 'Peter Kamau Mwangi',
+    crNumber: 'CR1120983344215-7',
+    locationUuid: '',
+    date: TODAY,
+    closed: true,
+    lineItems: [
+      { id: 'cb-3-1', service: 'Consultation', code: 'SVC-CONS', amount: 500, paidAmount: 500 },
+      { id: 'cb-3-2', service: 'Laboratory · Malaria RDT', code: 'LAB-MRDT', amount: 300, paidAmount: 300 },
+    ],
+    payments: [
+      { id: 'p-cb-3-1', itemId: 'cb-3-1', service: 'Consultation', amount: 500, method: 'M-Pesa', reference: 'SFH3Q9K2BB', receiptNo: 'RCT-2026-4002', at: `${TODAY}T07:41:00` },
+      { id: 'p-cb-3-2', itemId: 'cb-3-2', service: 'Laboratory · Malaria RDT', amount: 300, method: 'M-Pesa', reference: 'SFH3Q9K3CC', receiptNo: 'RCT-2026-4003', at: `${TODAY}T07:55:00` },
+    ],
+  },
+];
+
+const clone = (b: CashBillSeed): CashBill => ({
+  ...b,
+  source: 'CASH',
+  lineItems: b.lineItems.map((i) => ({ ...i })),
+  payments: b.payments.map((p) => ({ ...p })),
+});
+
+/** Pure cash bills (patient pays every line before service). */
+export async function getCashBills(_locationUuid?: string): Promise<CashBill[]> {
+  await wait(200);
+  return CASH_BILLS.map(clone);
+}
+
+/** The copay slice of SHA claims — the cash portion settled at the cash point. */
+export async function getCopayBills(): Promise<CashBill[]> {
+  const claims = await getClaimsByStatuses([
+    'DRAFT',
+    'PREAUTH_PENDING',
+    'SUBMITTED',
+    'APPROVED',
+    'REJECTED',
+    'RECALLED',
+    'PAID',
+  ]);
+  return claims
+    .map((c) => ({ c, copay: c.bill?.copay ?? splitBillForSha(c.lines).copay }))
+    .filter(({ copay }) => copay > 0)
+    .map(({ c, copay }) => {
+      const itemId = `copay-${c.id}`;
+      const state = copayState.get(itemId) ?? { paidAmount: 0, payments: [], closed: false };
+      return {
+        id: `copaybill-${c.id}`,
+        billNo: c.bill?.billNo ?? c.claimCode.replace('CLM', 'INV'),
+        patientName: c.patientName,
+        crNumber: c.crNumber,
+        locationUuid: '',
+        date: TODAY,
+        source: 'SHA_COPAY' as const,
+        claimCode: c.claimCode,
+        closed: state.closed,
+        lineItems: [{ id: itemId, service: `SHA copay · ${c.fund}`, code: c.claimCode, amount: copay, paidAmount: state.paidAmount }],
+        payments: state.payments.map((p) => ({ ...p })),
+      };
+    });
+}
+
+/** Every payable-at-cash-point bill: pure cash + SHA copays. */
+export async function getPayableBills(locationUuid?: string): Promise<CashBill[]> {
+  const [cash, copay] = await Promise.all([getCashBills(locationUuid), getCopayBills()]);
+  return [...cash, ...copay].sort((a, b) => (a.date < b.date ? 1 : -1));
+}
+
+export interface PayInput {
+  amount: number;
+  method: PaymentMethod;
+  reference?: string;
+}
+
+/** Pay an amount against a bill line item (partial allowed, never over its balance). */
+export async function payItem(billId: string, itemId: string, input: PayInput): Promise<PaymentEntry> {
+  await wait(300);
+  const now = new Date().toISOString();
+  const receiptNo = nextReceiptNo();
+  const { method, reference } = input;
+
+  if (itemId.startsWith('copay-')) {
+    const state = copayState.get(itemId) ?? { paidAmount: 0, payments: [], closed: false };
+    const entry: PaymentEntry = { id: `p-${receiptNo}`, itemId, service: 'SHA copay', amount: input.amount, method, reference, receiptNo, at: now };
+    copayState.set(itemId, { ...state, paidAmount: state.paidAmount + input.amount, payments: [...state.payments, entry] });
+    return entry;
+  }
+
+  let entry: PaymentEntry | undefined;
+  CASH_BILLS = CASH_BILLS.map((b) => {
+    if (b.id !== billId) {
+      return b;
+    }
+    const item = b.lineItems.find((i) => i.id === itemId);
+    if (!item) {
+      return b;
+    }
+    const amount = Math.min(input.amount, itemBalance(item));
+    entry = { id: `p-${receiptNo}`, itemId, service: item.service, amount, method, reference, receiptNo, at: now };
+    return {
+      ...b,
+      lineItems: b.lineItems.map((i) => (i.id === itemId ? { ...i, paidAmount: i.paidAmount + amount } : i)),
+      payments: [...b.payments, entry as PaymentEntry],
+    };
+  });
+  return entry ?? { id: `p-${receiptNo}`, itemId, service: '', amount: 0, method, reference, receiptNo, at: now };
+}
+
+export async function closeBill(billId: string): Promise<void> {
+  await wait(250);
+  if (billId.startsWith('copaybill-')) {
+    const itemId = billId.replace('copaybill-', 'copay-');
+    const state = copayState.get(itemId) ?? { paidAmount: 0, payments: [], closed: false };
+    copayState.set(itemId, { ...state, closed: true });
+    return;
+  }
+  CASH_BILLS = CASH_BILLS.map((b) =>
+    b.id === billId && b.lineItems.reduce((s, i) => s + (i.amount - i.paidAmount), 0) === 0 ? { ...b, closed: true } : b,
+  );
+}

package/src/billing/dashboard/v2/cash-checklist/payment-drawer.component.scss

@@ -0,0 +1,246 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+@use '@carbon/colors';
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+.overlay {
+  position: fixed;
+  inset: 0;
+  background-color: rgba(0, 0, 0, 0.5);
+  z-index: 8000;
+}
+
+.drawer {
+  position: fixed;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: 34rem;
+  max-width: 100%;
+  background-color: colors.$white;
+  z-index: 8001;
+  display: flex;
+  flex-direction: column;
+  box-shadow: -2px 0 8px rgba(0, 0, 0, 0.15);
+  animation: paymentDrawerIn 160ms ease-out;
+}
+
+@keyframes paymentDrawerIn {
+  from {
+    transform: translateX(100%);
+  }
+  to {
+    transform: translateX(0);
+  }
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: layout.$spacing-05;
+  border-bottom: 1px solid $ui-03;
+}
+
+.title {
+  @include type.type-style('heading-compact-02');
+  color: $ui-05;
+  margin: 0;
+}
+
+.subtitle {
+  @include type.type-style('label-01');
+  color: $text-02;
+}
+
+.close {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: none;
+  border: none;
+  cursor: pointer;
+  color: $ui-05;
+  padding: layout.$spacing-02;
+
+  &:hover {
+    background-color: $ui-03;
+  }
+}
+
+.body {
+  flex: 1 1 auto;
+  overflow-y: auto;
+  padding: layout.$spacing-06;
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-06;
+
+  /* Carbon reserves a helper/invalid-text row under each field; collapse it when
+     empty so fields sit closer together. */
+  :global(.cds--form-requirement:empty) {
+    display: none;
+  }
+}
+
+.itemName {
+  @include type.type-style('heading-compact-02');
+  color: $ui-05;
+}
+
+.summaryCard {
+  display: flex;
+  padding: layout.$spacing-05;
+  border: 1px solid $ui-03;
+  background-color: $ui-01;
+}
+
+.summaryItem {
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-02;
+  flex: 1 1 0;
+  min-width: 0;
+
+  & + & {
+    padding-left: layout.$spacing-05;
+    border-left: 1px solid $ui-03;
+  }
+}
+
+.summaryLabel {
+  @include type.type-style('label-01');
+  text-transform: uppercase;
+  letter-spacing: 0.02em;
+  color: $text-03;
+}
+
+.summaryValue {
+  @include type.type-style('heading-compact-01');
+  color: $ui-05;
+  font-variant-numeric: tabular-nums;
+}
+
+.summaryBalance {
+  color: colors.$red-60;
+}
+
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-06;
+  width: 100%;
+}
+
+.sectionLabel {
+  @include type.type-style('label-01');
+  text-transform: uppercase;
+  letter-spacing: 0.02em;
+  font-weight: 700;
+  color: $text-02;
+  padding-bottom: layout.$spacing-03;
+  border-bottom: 1px solid $ui-03;
+  margin-bottom: -(layout.$spacing-02);
+}
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-03;
+}
+
+.fieldLabel {
+  @include type.type-style('label-01');
+  color: $text-02;
+}
+
+.methodCard {
+  display: flex;
+  align-items: center;
+  gap: layout.$spacing-03;
+  padding: layout.$spacing-04 layout.$spacing-05;
+  border: 1px solid $ui-03;
+  background-color: $ui-01;
+}
+
+.methodDot {
+  width: 0.5rem;
+  height: 0.5rem;
+  border-radius: 50%;
+  background-color: colors.$green-50;
+  flex-shrink: 0;
+}
+
+.methodCardText {
+  @include type.type-style('body-compact-01');
+  font-weight: 600;
+  color: $ui-05;
+}
+
+.methodCardSub {
+  @include type.type-style('label-01');
+  color: $text-03;
+  margin-left: auto;
+}
+
+.required {
+  color: colors.$red-60;
+  margin-left: 2px;
+}
+
+.methodNote {
+  @include type.type-style('body-compact-01');
+  color: $text-02;
+  margin: 0;
+}
+
+.divider {
+  border: none;
+  border-top: 1px solid $ui-03;
+  margin: 0;
+  width: 100%;
+}
+
+.newBalance {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: layout.$spacing-05;
+  padding: layout.$spacing-04 layout.$spacing-05;
+  border: 1px solid transparent;
+  @include type.type-style('label-01');
+  text-transform: uppercase;
+  letter-spacing: 0.02em;
+}
+
+.newBalanceValue {
+  @include type.type-style('heading-compact-02');
+  color: inherit;
+  font-variant-numeric: tabular-nums;
+  text-transform: none;
+  letter-spacing: 0;
+}
+
+/* Outstanding balance remaining */
+.newBalanceDue {
+  border-color: colors.$red-20;
+  background-color: colors.$red-10;
+  color: colors.$red-70;
+}
+
+/* Fully paid after this payment */
+.newBalanceClear {
+  border-color: colors.$green-30;
+  background-color: colors.$green-10;
+  color: colors.$green-70;
+}
+
+.footer {
+  display: flex;
+  border-top: 1px solid $ui-03;
+
+  :global(.cds--btn) {
+    flex: 1 1 50%;
+    max-width: none;
+  }
+}

package/src/billing/dashboard/v2/cash-checklist/payment-drawer.component.tsx

@@ -0,0 +1,182 @@
+import React, { useState } from 'react';
+import { Button, Dropdown, NumberInput, TextInput } from '@carbon/react';
+import { Close } from '@carbon/react/icons';
+import styles from './payment-drawer.component.scss';
+import { itemBalance, type BillLineItem, type BillSource, type PayInput, type PaymentMethod } from './cash-checklist.resource';
+
+const money = (n: number) => `KES ${n.toLocaleString('en-KE')}`;
+
+interface PaymentDrawerProps {
+  item: BillLineItem;
+  source: BillSource;
+  busy?: boolean;
+  onClose: () => void;
+  onSubmit: (input: PayInput) => void;
+}
+
+/** Side drawer to record a payment against a bill line item. Defaults to M-Pesa
+ *  (reference entered manually pre-integration); SHA copays may also settle via SHA. */
+const PaymentDrawer: React.FC<PaymentDrawerProps> = ({ item, source, busy, onClose, onSubmit }) => {
+  const balance = itemBalance(item);
+  const methods: PaymentMethod[] = source === 'SHA_COPAY' ? ['M-Pesa', 'SHA'] : ['M-Pesa'];
+  const [method, setMethod] = useState<PaymentMethod>('M-Pesa');
+  const [reference, setReference] = useState('');
+  const [amount, setAmount] = useState<number>(balance);
+  const [refError, setRefError] = useState('');
+  const [amtError, setAmtError] = useState('');
+
+  const amountValid = amount > 0 && amount <= balance;
+  const refValid = method !== 'M-Pesa' || reference.trim().length > 0;
+  const canSubmit = amountValid && refValid && !busy;
+  const newBalance = Math.max(0, balance - (amountValid ? amount : 0));
+
+  const handleAmount = (value: string | number) => {
+    const v = Number(value) || 0;
+    setAmount(v);
+    if (v <= 0) {
+      setAmtError('Enter an amount to pay.');
+    } else if (v > balance) {
+      setAmtError(`Amount cannot exceed the balance of ${money(balance)}.`);
+    } else {
+      setAmtError('');
+    }
+  };
+
+  const submit = () => {
+    if (!amountValid) {
+      setAmtError(amount <= 0 ? 'Enter an amount to pay.' : `Amount cannot exceed the balance of ${money(balance)}.`);
+    }
+    if (!refValid) {
+      setRefError('Enter the M-Pesa reference number.');
+    }
+    if (!amountValid || !refValid) {
+      return;
+    }
+    onSubmit({ amount, method, reference: method === 'M-Pesa' ? reference.trim() : undefined });
+  };
+
+  return (
+    <>
+      <div className={styles.overlay} onClick={onClose} />
+      <aside className={styles.drawer} role="dialog" aria-label="Record payment">
+        <header className={styles.header}>
+          <div>
+            <h5 className={styles.title}>Record payment</h5>
+            <span className={styles.subtitle}>{item.service}</span>
+          </div>
+          <button type="button" className={styles.close} onClick={onClose} aria-label="Close">
+            <Close size={20} />
+          </button>
+        </header>
+
+        <div className={styles.body}>
+          <div className={styles.summaryCard}>
+            <div className={styles.summaryItem}>
+              <span className={styles.summaryLabel}>Amount</span>
+              <span className={styles.summaryValue}>{money(item.amount)}</span>
+            </div>
+            <div className={styles.summaryItem}>
+              <span className={styles.summaryLabel}>Paid</span>
+              <span className={styles.summaryValue}>{money(item.paidAmount)}</span>
+            </div>
+            <div className={styles.summaryItem}>
+              <span className={styles.summaryLabel}>Balance</span>
+              <span className={`${styles.summaryValue} ${styles.summaryBalance}`}>{money(balance)}</span>
+            </div>
+          </div>
+
+          <div className={styles.form}>
+            <div className={styles.sectionLabel}>Payment</div>
+            {methods.length > 1 ? (
+              <Dropdown
+                id="pay-method"
+                titleText="Payment method"
+                label="Select method"
+                items={methods}
+                selectedItem={method}
+                onChange={({ selectedItem }) => {
+                  setMethod((selectedItem as PaymentMethod) ?? 'M-Pesa');
+                  setRefError('');
+                }}
+              />
+            ) : (
+              <div className={styles.field}>
+                <span className={styles.fieldLabel}>Payment method</span>
+                <div className={styles.methodCard}>
+                  <span className={styles.methodDot} />
+                  <span className={styles.methodCardText}>M-Pesa</span>
+                  <span className={styles.methodCardSub}>Mobile money</span>
+                </div>
+              </div>
+            )}
+
+            {method === 'M-Pesa' ? (
+              <TextInput
+                id="mpesa-ref"
+                labelText={
+                  <span>
+                    M-Pesa reference number<span className={styles.required}>*</span>
+                  </span>
+                }
+                placeholder="e.g. SGH7X1K2QP"
+                value={reference}
+                invalid={!!refError}
+                invalidText={refError}
+                onFocus={() => {
+                  if (!reference.trim()) {
+                    setRefError('M-Pesa reference number is required.');
+                  }
+                }}
+                onChange={(e) => {
+                  setReference(e.target.value);
+                  setRefError(e.target.value.trim() ? '' : 'M-Pesa reference number is required.');
+                }}
+              />
+            ) : (
+              <p className={styles.methodNote}>Settled against the patient&apos;s SHA cover.</p>
+            )}
+
+            <NumberInput
+              id="pay-amount"
+              label={
+                <span>
+                  Amount to pay (KES)<span className={styles.required}>*</span>
+                </span>
+              }
+              helperText={`Up to the balance of ${money(balance)}`}
+              min={0}
+              max={balance}
+              value={amount}
+              invalid={!!amtError}
+              invalidText={amtError}
+              onFocus={() => {
+                if (!amount || amount <= 0) {
+                  setAmtError('Amount to pay is required.');
+                }
+              }}
+              onChange={(_e, { value }) => handleAmount(value)}
+            />
+
+            <hr className={styles.divider} />
+
+            <div className={`${styles.newBalance} ${newBalance > 0 ? styles.newBalanceDue : styles.newBalanceClear}`}>
+              <span>{newBalance > 0 ? 'Balance after payment' : 'Fully paid after payment'}</span>
+              <span className={styles.newBalanceValue}>{money(newBalance)}</span>
+            </div>
+          </div>
+        </div>
+
+        <footer className={styles.footer}>
+          <Button kind="secondary" onClick={onClose}>
+            Cancel
+          </Button>
+          <Button kind="primary" disabled={!canSubmit} onClick={submit}>
+            {busy ? 'Recording…' : 'Record payment'}
+          </Button>
+        </footer>
+      </aside>
+    </>
+  );
+};
+
+export default PaymentDrawer;