@ampath/esm-dha-workflow-app 4.0.0-next.33 → 4.0.0-next.331

package/src/billing/dashboard/v2/patient-bill-details/payment-mode.ts

@@ -0,0 +1,124 @@
+import { type PatientFacilityBillDetails } from '../types';
+
+/**
+ * Who is paying for a bill line, and what that means for how the bill is shown.
+ *
+ * A bill's payer is not one field. `payment_scheme` carries the scheme when ETL knows it,
+ * a consent token means the visit was authorised through SHA/HIE, and the line's price
+ * name is what the cashier actually charged against. The rules for reading those live
+ * here rather than in a component, so a page, a table cell and a summary tile can't come
+ * to different conclusions about the same bill.
+ */
+export type PaymentModeKey = 'cash' | 'sha' | 'copay' | 'insurance' | 'unknown';
+
+export interface PaymentModeDescriptor {
+  key: PaymentModeKey;
+  /** What to call it on screen. */
+  label: string;
+  /** The scheme's own name where there is one — "Social Health Insurance Fund", a private
+      insurer — which `label` is too short to carry. */
+  schemeName?: string;
+  /** Carbon tag colour, so the same payer is the same colour everywhere. */
+  tagType: 'green' | 'blue' | 'teal' | 'purple' | 'gray';
+  /** Whether this bill has a claim behind it worth linking to. */
+  hasClaim: boolean;
+  /** Whether the patient pays part of it themselves — the reason a co-pay is its own
+      mode rather than a kind of insurance. */
+  hasPatientPortion: boolean;
+}
+
+const norm = (value?: string | null): string => (value ?? '').trim().toUpperCase();
+
+/** The scheme as the bill records it, cased for reading rather than matching. */
+const schemeLabel = (value?: string | null): string | undefined => {
+  const v = (value ?? '').trim();
+  return v ? v : undefined;
+};
+
+/**
+ * A bill line's payment mode.
+ *
+ * Order matters: a line can satisfy more than one test — a SHA claim with a co-pay has
+ * both a consent token and a patient portion — and the more specific answer is the useful
+ * one, so co-pay is decided before SHA and SHA before "some insurer".
+ */
+export function paymentModeOf(line?: Partial<PatientFacilityBillDetails> | null): PaymentModeDescriptor {
+  if (!line) {
+    return { key: 'unknown', label: 'Unknown', tagType: 'gray', hasClaim: false, hasPatientPortion: false };
+  }
+
+  const scheme = norm(line.payment_scheme);
+  const name = schemeLabel(line.payment_scheme);
+  const hasToken = Boolean((line.consent_token ?? '').trim());
+
+  // A co-pay is a bill the patient part-pays alongside a payer, so it is neither cash nor
+  // a plain insurance line and is worth naming as itself.
+  if (scheme.includes('COPAY') || scheme.includes('CO-PAY')) {
+    return {
+      key: 'copay',
+      label: 'Co-pay',
+      schemeName: name,
+      tagType: 'purple',
+      hasClaim: hasToken,
+      hasPatientPortion: true,
+    };
+  }
+
+  if (scheme.includes('SHA') || scheme.includes('SHIF') || scheme.includes('SOCIAL HEALTH') || hasToken) {
+    return { key: 'sha', label: 'SHA', schemeName: name, tagType: 'teal', hasClaim: true, hasPatientPortion: false };
+  }
+
+  if (scheme.includes('CASH') || scheme.includes('SELF')) {
+    return { key: 'cash', label: 'Cash', schemeName: name, tagType: 'green', hasClaim: false, hasPatientPortion: true };
+  }
+
+  // Named scheme that is none of the above: another insurer. Kept as one mode rather than
+  // one per company, since what changes between them is the name and nothing else.
+  if (name) {
+    return {
+      key: 'insurance',
+      label: 'Insurance',
+      schemeName: name,
+      tagType: 'blue',
+      hasClaim: hasToken,
+      hasPatientPortion: false,
+    };
+  }
+
+  // No scheme and no token is how a straight cash bill usually arrives.
+  return { key: 'cash', label: 'Cash', tagType: 'green', hasClaim: false, hasPatientPortion: true };
+}
+
+/**
+ * The payment mode for a whole bill, which is a set of lines.
+ *
+ * A visit's lines can be split across payers — an insured consultation with a cash
+ * pharmacy item. Rather than pick a winner, that is reported as what it is, so the page
+ * can say so instead of labelling the whole bill after whichever line happened to be
+ * first.
+ */
+export function billPaymentModes(lines: PatientFacilityBillDetails[] = []): {
+  modes: PaymentModeDescriptor[];
+  primary: PaymentModeDescriptor;
+  mixed: boolean;
+} {
+  const byKey = new Map<PaymentModeKey, PaymentModeDescriptor>();
+  for (const line of lines) {
+    const mode = paymentModeOf(line);
+    if (!byKey.has(mode.key)) {
+      byKey.set(mode.key, mode);
+    }
+  }
+  const modes = [...byKey.values()];
+  const primary =
+    modes.find((m) => m.hasClaim) ?? modes.find((m) => m.key === 'sha') ?? modes[0] ?? paymentModeOf(null);
+  return { modes, primary, mixed: modes.length > 1 };
+}
+
+
+export function resolveConsentTokenFromBillLines(
+  lines: Array<Partial<PatientFacilityBillDetails> | null | undefined> = [],
+): string {
+  const shaLine = lines.find((l) => paymentModeOf(l).key === 'sha');
+  return (shaLine?.consent_token ?? '').trim();
+}

package/src/billing/dashboard/v2/patient-bill-details/workspaces/add-claim-line/add-claim-line.workspace.scss

@@ -0,0 +1,27 @@
+@use '@carbon/layout';
+
+.form {
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+  height: 100%;
+}
+
+.formContent {
+  display: flex;
+  flex-direction: column;
+  padding: layout.$spacing-05;
+  overflow-y: auto;
+}
+
+.buttonSet {
+  display: flex;
+  width: 100%;
+  margin-top: layout.$spacing-05;
+}
+
+.button {
+  flex: 1;
+  max-width: 50%;
+  height: layout.$spacing-10;
+}

package/src/billing/dashboard/v2/patient-bill-details/workspaces/add-claim-line/add-claim-line.workspace.tsx

@@ -0,0 +1,222 @@
+import React, { useEffect, useState } from 'react';
+import { Button, ButtonSet, Form, InlineLoading, InlineNotification, Stack, TextInput } from '@carbon/react';
+import { showSnackbar, type DefaultWorkspaceProps } from '@openmrs/esm-framework';
+import styles from './add-claim-line.workspace.scss';
+import { type AddClaimLineDto, type PatientFacilityBillDetails } from '../../../types';
+import { addClaimItem } from '../../../../../billing-claims.resource';
+import { ensureInterventionOnVisit } from '../../../../../../claims/interventions.resource';
+import { extractPreauthStatus, getPreauthPreview } from '../../../../../../claims/claims.resource';
+import { asBool, getStoredPreauthCode, needsNormalPreauth } from '../../../preauth/preauth.resource';
+
+interface AddClaimLineWorkspaceProps extends DefaultWorkspaceProps {
+  billItem: PatientFacilityBillDetails;
+  locationUuid: string;
+  /** Visit claim token — bill lines often have consent_token null */
+  consentToken?: string;
+  onSuccess?: () => void;
+}
+
+function errorMessage(error: unknown): string {
+  if (error == null) {
+    return 'An error occurred while adding the claim line. Kindly retry or contact support.';
+  }
+  if (typeof error === 'string') {
+    return error;
+  }
+  const e = error as { message?: unknown; responseBody?: { message?: unknown } };
+  const fromBody = e.responseBody?.message;
+  if (Array.isArray(fromBody)) {
+    return fromBody.join(', ');
+  }
+  if (typeof fromBody === 'string' && fromBody.trim()) {
+    return fromBody;
+  }
+  if (typeof e.message === 'string' && e.message.trim()) {
+    return e.message;
+  }
+  return 'An error occurred while adding the claim line. Kindly retry or contact support.';
+}
+
+const AddClaimLineWorkspace: React.FC<AddClaimLineWorkspaceProps> = ({
+  billItem,
+  locationUuid,
+  consentToken: consentTokenProp,
+  onSuccess,
+  closeWorkspace,
+}) => {
+  const [loading, setLoading] = useState(false);
+  const [checkingPreauth, setCheckingPreauth] = useState(false);
+  const [preauthBlocked, setPreauthBlocked] = useState(false);
+  const [preauthCode, setPreauthCode] = useState<string | undefined>();
+  const resolvedToken = (consentTokenProp || billItem.consent_token || '').trim();
+
+  useEffect(() => {
+    if (!needsNormalPreauth(billItem) || !resolvedToken) {
+      setPreauthBlocked(false);
+      setPreauthCode(getStoredPreauthCode(resolvedToken, billItem.intervention_code));
+      return;
+    }
+
+    let cancelled = false;
+    const run = async () => {
+      setCheckingPreauth(true);
+      try {
+        const stored = getStoredPreauthCode(resolvedToken, billItem.intervention_code);
+        setPreauthCode(stored);
+        const preview = await getPreauthPreview(resolvedToken, locationUuid);
+        const status = extractPreauthStatus(preview);
+        if (!cancelled) {
+          const ok = status === 'FINALISED' || status === 'FINALIZED' || asBool(billItem.preauth_approved);
+          setPreauthBlocked(!ok);
+        }
+      } catch {
+        if (!cancelled) {
+          setPreauthBlocked(
+            !asBool(billItem.preauth_approved) &&
+              !getStoredPreauthCode(resolvedToken, billItem.intervention_code),
+          );
+        }
+      } finally {
+        if (!cancelled) setCheckingPreauth(false);
+      }
+    };
+    run();
+    return () => {
+      cancelled = true;
+    };
+  }, [billItem, resolvedToken, locationUuid]);
+
+  function getClaimLineDto(): AddClaimLineDto {
+    const dto: AddClaimLineDto = {
+      consentToken: resolvedToken,
+      interventionCode: billItem.intervention_code,
+      unitPrice: String(billItem.item_price),
+      quantity: String(billItem.item_quantity),
+      locationUuid: locationUuid,
+    };
+    const code = preauthCode || getStoredPreauthCode(resolvedToken, billItem.intervention_code);
+    if (code) {
+      dto.preauthCode = code;
+    }
+    return dto;
+  }
+
+  async function handleAddClaimLineItem(event: React.FormEvent) {
+    event.preventDefault();
+    if (!resolvedToken) {
+      showSnackbar({
+        kind: 'error',
+        title: 'No claim token',
+        subtitle: 'Start a claim visit for this patient before adding a claim line.',
+      });
+      return;
+    }
+    if (!billItem.intervention_code) {
+      showSnackbar({
+        kind: 'error',
+        title: 'Missing intervention',
+        subtitle: 'This bill line has no intervention code.',
+      });
+      return;
+    }
+    if (preauthBlocked) {
+      showSnackbar({
+        kind: 'error',
+        title: 'Preauth required',
+        subtitle: 'Wait until preauth is FINALISED before adding a claim line for this intervention.',
+      });
+      return;
+    }
+
+    setLoading(true);
+    try {
+      await ensureInterventionOnVisit(resolvedToken, billItem.intervention_code, locationUuid);
+
+      const resp = await addClaimItem(getClaimLineDto());
+      if (resp && resp['error']) {
+        const detail = Array.isArray(resp['message'])
+          ? resp['message'].join(', ')
+          : (resp['message'] as string) || errorMessage(resp);
+        showSnackbar({
+          title: (resp['error'] as string) ?? 'Error Adding Claim Line',
+          kind: 'error',
+          subtitle: detail,
+        });
+      } else {
+        showSnackbar({
+          title: 'Success Adding Claim Line',
+          kind: 'success',
+          subtitle: 'Claim item added successfully',
+        });
+        onSuccess?.();
+        closeWorkspace();
+      }
+    } catch (error) {
+      showSnackbar({
+        kind: 'error',
+        title: 'Error Adding Claim Line',
+        subtitle: errorMessage(error),
+      });
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <Form className={styles.form} onSubmit={handleAddClaimLineItem}>
+      <div className={styles.formContent}>
+        <Stack gap={5}>
+          {preauthBlocked ? (
+            <InlineNotification
+              kind="warning"
+              lowContrast
+              hideCloseButton
+              title="Preauth not finalised"
+              subtitle="Raise and finalise preauth for this intervention before adding a claim line."
+            />
+          ) : null}
+          {preauthCode ? (
+            <InlineNotification
+              kind="info"
+              lowContrast
+              hideCloseButton
+              title="Preauth code"
+              subtitle={preauthCode}
+            />
+          ) : null}
+          <TextInput id="bill-item" labelText="Billable item" value={billItem.billable_service ?? '—'} readOnly />
+          <TextInput
+            id="intervention-code"
+            labelText="Intervention code"
+            value={billItem.intervention_code ?? '—'}
+            readOnly
+          />
+          <TextInput id="unit-price" labelText="Unit price" value={`Ksh ${billItem.item_price}`} readOnly />
+          <TextInput id="quantity" labelText="Quantity" value={billItem.item_quantity} readOnly />
+        </Stack>
+      </div>
+
+      <ButtonSet className={styles.buttonSet}>
+        <Button className={styles.button} kind="secondary" onClick={() => closeWorkspace()} disabled={loading}>
+          Cancel
+        </Button>
+        <Button
+          className={styles.button}
+          kind="primary"
+          type="submit"
+          disabled={loading || checkingPreauth || preauthBlocked || !resolvedToken}
+        >
+          {loading ? (
+            <InlineLoading description="Adding..." />
+          ) : checkingPreauth ? (
+            <InlineLoading description="Checking preauth..." />
+          ) : (
+            'Add claim line'
+          )}
+        </Button>
+      </ButtonSet>
+    </Form>
+  );
+};
+
+export default AddClaimLineWorkspace;

package/src/billing/dashboard/v2/patient-bill-details/workspaces/bill-item-payment/bill-item-payment.workspace.scss

@@ -0,0 +1,27 @@
+@use '@carbon/layout';
+
+.form {
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+  height: 100%;
+}
+
+.formContent {
+  display: flex;
+  flex-direction: column;
+  padding: layout.$spacing-05;
+  overflow-y: auto;
+}
+
+.buttonSet {
+  display: flex;
+  width: 100%;
+  margin-top: layout.$spacing-05;
+}
+
+.button {
+  flex: 1;
+  max-width: 50%;
+  height: layout.$spacing-10;
+}

package/src/billing/dashboard/v2/patient-bill-details/workspaces/bill-item-payment/bill-item-payment.workspace.tsx

@@ -0,0 +1,109 @@
+import React, { useEffect, useMemo, useState } from 'react';
+import { Button, ButtonSet, Form, InlineLoading, Select, SelectItem, Stack, TextInput } from '@carbon/react';
+import { showSnackbar, type DefaultWorkspaceProps } from '@openmrs/esm-framework';
+import styles from './bill-item-payment.workspace.scss';
+import { type PatientFacilityBillDetails } from '../../../types';
+import { type PaymentMode } from '../../../../../../shared/types';
+import { fetchPaymentModes } from '../../../../../../shared/services/billing.resource';
+import { payBillItem } from '../../../../../billing-claims.resource';
+
+interface BillItemPaymentWorkspaceProps extends DefaultWorkspaceProps {
+  billItem: PatientFacilityBillDetails;
+  onPay?: () => void;
+}
+
+const BillItemPaymentWorkspace: React.FC<BillItemPaymentWorkspaceProps> = ({ billItem, onPay, closeWorkspace }) => {
+  const [amountToPay, setAmountToPay] = useState<number>(0);
+  const [paymentModes, setPaymentModes] = useState<PaymentMode[]>([]);
+  const [selectedPaymentModeUuid, setSelectedPaymentModeUuid] = useState<string>('');
+  const [submitting, setSubmitting] = useState<boolean>(false);
+
+  const billItemPaymentMode = useMemo(
+    () => paymentModes.find((pm) => pm.name === billItem?.payment_scheme),
+    [paymentModes, billItem],
+  );
+
+  useEffect(() => {
+    if (billItem) {
+      fetchPaymentModes().then(setPaymentModes);
+    }
+  }, [billItem]);
+
+  // Either the scheme resolves its own payment mode, or the user picks one.
+  const resolvedPaymentModeUuid = billItemPaymentMode?.uuid ?? selectedPaymentModeUuid;
+  const canPay = !submitting && Boolean(resolvedPaymentModeUuid) && amountToPay > 0;
+
+  async function payForBillItem(event: React.FormEvent) {
+    event.preventDefault();
+    setSubmitting(true);
+    try {
+      const resp = await payBillItem(billItem.bill_uuid, {
+        instanceType: resolvedPaymentModeUuid,
+        amountTendered: amountToPay,
+        amount: billItem.item_total_price,
+      });
+      if (resp) {
+        showSnackbar({
+          kind: 'success',
+          title: 'Bill item payment succesfully made',
+          subtitle: '',
+        });
+        onPay?.();
+        closeWorkspace();
+      }
+    } catch (error) {
+      showSnackbar({
+        kind: 'error',
+        title: 'An error occurred while making bill item payment',
+        subtitle: 'An error occurred while making bill item payment, please try again or contact support',
+      });
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  return (
+    <Form className={styles.form} onSubmit={payForBillItem}>
+      <div className={styles.formContent}>
+        <Stack gap={5}>
+          <TextInput id="bill-item" labelText="Billable item" value={billItem.billable_service ?? '—'} readOnly />
+          <TextInput id="bill-item-amount" labelText="Amount" value={`Ksh ${billItem.item_total_price}`} readOnly />
+          {billItemPaymentMode ? (
+            <TextInput id="payment-mode" labelText="Payment mode" value={billItemPaymentMode.name} readOnly />
+          ) : (
+            <Select
+              id="payment-mode"
+              labelText="Payment mode"
+              value={selectedPaymentModeUuid}
+              onChange={($event) => setSelectedPaymentModeUuid($event.target.value)}
+            >
+              <SelectItem value="" text="Select" />
+              {paymentModes.map((pm) => (
+                <SelectItem key={pm.uuid} value={pm.uuid} text={pm.name} />
+              ))}
+            </Select>
+          )}
+          <TextInput
+            id="pay-amount"
+            labelText="Pay amount"
+            type="number"
+            min={0}
+            value={amountToPay || ''}
+            onChange={(v) => setAmountToPay(Number(v.target.value))}
+          />
+        </Stack>
+      </div>
+
+      <ButtonSet className={styles.buttonSet}>
+        <Button className={styles.button} kind="secondary" onClick={() => closeWorkspace()}>
+          Cancel
+        </Button>
+        <Button className={styles.button} kind="primary" type="submit" disabled={!canPay}>
+          {submitting ? <InlineLoading description="Paying..." /> : 'Pay'}
+        </Button>
+      </ButtonSet>
+    </Form>
+  );
+};
+
+export default BillItemPaymentWorkspace;