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

package/src/billing/dashboard/v3/preauth/preauth-list.component.tsx

@@ -0,0 +1,281 @@
+import React, { useCallback, useEffect, useState } from 'react';
+import {
+  Button,
+  DataTableSkeleton,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+  Tag,
+} from '@carbon/react';
+import { Renew } from '@carbon/react/icons';
+import { launchWorkspace, showSnackbar } from '@openmrs/esm-framework';
+import {
+  checkPreauthStatus,
+  invalidatePreauthPreview,
+  isPreauthNeedsClarification,
+  type PreauthCheckKind,
+} from '../../../../claims/claims.resource';
+import EmptyState from '../shared/empty-state.component';
+import TableToolbar from '../shared/table-toolbar.component';
+import { type PatientFacilityBillDetails } from '../types';
+import styles from './preauth-list.component.scss';
+import {
+  fetchActiveVisitForPatient,
+  fetchPreauthBillItems,
+  interventionFlagsFromBillItem,
+  needsElectivePreauth,
+  preauthFormLabel,
+  resolveConsentTokenForVisit,
+} from './preauth.resource';
+import PreauthStatusTag, { type PreauthStatusDisplayKind } from './preauth-status-tag.component';
+
+interface PreauthListProps {
+  locationUuid: string;
+  billingDate: string;
+  onDateChange?: (value: string) => void;
+}
+
+type RowMeta = {
+  kind: PreauthStatusDisplayKind;
+  status?: string;
+  preauthCode?: string;
+  notes?: string;
+};
+
+const PreauthList: React.FC<PreauthListProps> = ({ locationUuid, billingDate, onDateChange }) => {
+  const [items, setItems] = useState<PatientFacilityBillDetails[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [search, setSearch] = useState('');
+  const [rowMeta, setRowMeta] = useState<Record<string, RowMeta>>({});
+  const [rowTokens, setRowTokens] = useState<Record<string, string>>({});
+
+  const rowKey = (item: PatientFacilityBillDetails) =>
+    `${item.patient_uuid}-${item.intervention_code}-${item.order_no ?? item.bill_line_item_id ?? item.cashier_bill_line_item_uuid}`;
+
+  const load = useCallback(async () => {
+    if (!locationUuid || !billingDate) return;
+    setLoading(true);
+    try {
+      const data = await fetchPreauthBillItems(locationUuid, billingDate);
+      setItems(data);
+
+      const metaMap: Record<string, RowMeta> = {};
+      const tokenMap: Record<string, string> = {};
+
+      for (const item of data) {
+        const key = rowKey(item);
+        try {
+          const visit = await fetchActiveVisitForPatient(item.patient_uuid, locationUuid);
+          // Prefer visit attribute; fall back to ETL consent_token on the bill row
+          const token = resolveConsentTokenForVisit(visit) || item.consent_token || '';
+          tokenMap[key] = token;
+          if (!token) {
+            metaMap[key] = { kind: 'no_token' };
+            continue;
+          }
+          metaMap[key] = { kind: 'loading' };
+
+          const check = await checkPreauthStatus(token, locationUuid, item.intervention_code);
+          metaMap[key] = {
+            kind: check.kind as PreauthCheckKind,
+            status: check.status,
+            preauthCode: check.preauthCode,
+            notes: check.notes,
+          };
+        } catch {
+          // Visit fetch failed — still allow raise if ETL returned consent_token
+          const token = item.consent_token || '';
+          tokenMap[key] = token;
+          if (token) {
+            const check = await checkPreauthStatus(token, locationUuid, item.intervention_code);
+            metaMap[key] = {
+              kind: check.kind as PreauthCheckKind,
+              status: check.status,
+              preauthCode: check.preauthCode,
+              notes: check.notes,
+            };
+          } else {
+            metaMap[key] = { kind: 'error', status: 'Visit lookup failed' };
+          }
+        }
+      }
+      setRowTokens(tokenMap);
+      setRowMeta(metaMap);
+    } catch {
+      showSnackbar({
+        kind: 'error',
+        title: 'Error loading preauth items',
+        subtitle: 'Could not load bill items needing preauth. Reload or contact support.',
+      });
+      setItems([]);
+      setRowMeta({});
+      setRowTokens({});
+    } finally {
+      setLoading(false);
+    }
+  }, [locationUuid, billingDate]);
+
+  useEffect(() => {
+    load();
+  }, [load]);
+
+  const handleRaise = async (item: PatientFacilityBillDetails) => {
+    const key = rowKey(item);
+    const elective = needsElectivePreauth(item);
+    let token = rowTokens[key];
+    if (!token && !elective) {
+      const visit = await fetchActiveVisitForPatient(item.patient_uuid, locationUuid);
+      token = resolveConsentTokenForVisit(visit) || item.consent_token || '';
+      setRowTokens((p) => ({ ...p, [key]: token }));
+    }
+    if (!token && !elective) {
+      showSnackbar({
+        kind: 'error',
+        title: 'No claim token on visit',
+        subtitle: 'Start a claim visit for this patient before raising a normal preauth.',
+      });
+      return;
+    }
+    // Elective may start without a claim token — workspace runs pre-visit authorize.
+    if (!token && elective) {
+      token = item.consent_token || '';
+    }
+
+    const flags = interventionFlagsFromBillItem(item);
+    launchWorkspace('preauth-form-workspace', {
+      consentToken: token,
+      patientUuid: item.patient_uuid,
+      locationUuid,
+      isElective: elective,
+      billItem: item,
+      intervention: {
+        code: flags.code,
+        name: item.billable_service || flags.code,
+        requiresSurgicalPreauth: flags.requiresSurgicalPreauth,
+        requiresRenalPreauth: flags.requiresRenalPreauth,
+        requiresOncologyPreauth: flags.requiresOncologyPreauth,
+        requiresRadiologyPreauth: flags.requiresRadiologyPreauth,
+        requiresOpticalPreauth: flags.requiresOpticalPreauth,
+        requiredPreauthDocumentTypes: flags.requiredPreauthDocumentTypes,
+        applicableDocumentTypes: flags.applicableDocumentTypes,
+      },
+      onSuccess: async () => {
+        if (token) {
+          await invalidatePreauthPreview(token, locationUuid);
+        }
+        load();
+      },
+    });
+  };
+
+  const filtered = items.filter((item) => {
+    const term = search.trim().toLowerCase();
+    if (!term) return true;
+    return `${item.patient_name} ${item.intervention_code} ${item.billable_service}`.toLowerCase().includes(term);
+  });
+
+  return (
+    <div className={styles.preauthList}>
+      <div className={styles.toolbarRow}>
+        <TableToolbar
+          id="preauth-list"
+          search={search}
+          onSearch={setSearch}
+          searchPlaceholder="Search patient or intervention…"
+          onDate={onDateChange}
+        />
+        <Button
+          kind="ghost"
+          size="md"
+          renderIcon={Renew}
+          iconDescription="Refresh preauth status"
+          hasIconOnly
+          disabled={loading}
+          onClick={() => load()}
+          className={styles.refreshBtn}
+        />
+      </div>
+      {loading ? (
+        <DataTableSkeleton showHeader={false} rowCount={5} />
+      ) : items.length === 0 ? (
+        <EmptyState message="No bill items needing preauth for this date." />
+      ) : filtered.length === 0 ? (
+        <EmptyState message="No items match your search." />
+      ) : (
+        <Table aria-label="Preauth bill items" size="sm">
+          <TableHead>
+            <TableRow>
+              <TableHeader>Patient</TableHeader>
+              <TableHeader>Intervention</TableHeader>
+              <TableHeader>Order</TableHeader>
+              <TableHeader>Form</TableHeader>
+              <TableHeader>Bill status</TableHeader>
+              <TableHeader>Preauth</TableHeader>
+              <TableHeader>Action</TableHeader>
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {filtered.map((item) => {
+              const key = rowKey(item);
+              const flags = interventionFlagsFromBillItem(item);
+              const meta = rowMeta[key];
+              const elective = needsElectivePreauth(item);
+              // Not raised, terminal failure, or clarification → Raise / Resubmit.
+              // Other pending / finalised states stay blocked.
+              const canRaise =
+                meta?.kind === 'not_raised' ||
+                meta?.kind === 'failed' ||
+                isPreauthNeedsClarification(meta?.status ?? '') ||
+                (elective && meta?.kind === 'no_token');
+              const showNotes = Boolean(meta?.notes?.trim()) && meta?.kind !== 'not_raised';
+              return (
+                <TableRow key={key}>
+                  <TableCell>
+                    <div>{item.patient_name}</div>
+                    <div className={styles.muted}>{item.cr_no}</div>
+                  </TableCell>
+                  <TableCell>
+                    <div>{item.intervention_code}</div>
+                    <div className={styles.muted}>{item.service_type || item.billable_service}</div>
+                  </TableCell>
+                  <TableCell>{item.order_no ?? '—'}</TableCell>
+                  <TableCell>
+                    <Tag size="sm" type={elective ? 'magenta' : 'blue'}>
+                      {elective ? 'Elective' : preauthFormLabel(flags)}
+                    </Tag>
+                  </TableCell>
+                  <TableCell>{item.status ?? item.paid_status ?? '—'}</TableCell>
+                  <TableCell>
+                    <PreauthStatusTag
+                      kind={meta?.kind}
+                      status={meta?.status}
+                      preauthCode={meta?.preauthCode}
+                      loading={!meta || meta.kind === 'loading'}
+                    />
+                    {showNotes ? <div className={styles.notes}>{meta?.notes}</div> : null}
+                  </TableCell>
+                  <TableCell>
+                    {canRaise ? (
+                      <Button kind="ghost" size="sm" onClick={() => handleRaise(item)}>
+                        {meta?.kind === 'failed' || isPreauthNeedsClarification(meta?.status ?? '')
+                          ? 'Resubmit preauth'
+                          : 'Raise preauth'}
+                      </Button>
+                    ) : (
+                      '—'
+                    )}
+                  </TableCell>
+                </TableRow>
+              );
+            })}
+          </TableBody>
+        </Table>
+      )}
+    </div>
+  );
+};
+
+export default PreauthList;

package/src/billing/dashboard/v3/preauth/preauth-status-tag.component.tsx

@@ -0,0 +1,75 @@
+import React from 'react';
+import { InlineLoading, Tag } from '@carbon/react';
+import { isPreauthNeedsClarification, type PreauthCheckKind } from '../../../../claims/claims.resource';
+
+export type PreauthStatusDisplayKind = PreauthCheckKind | 'no_token' | 'loading';
+
+export interface PreauthStatusTagProps {
+  kind?: PreauthStatusDisplayKind | null;
+  status?: string;
+  preauthCode?: string;
+  loading?: boolean;
+}
+
+/**
+ * Shared preauth status Tag for list rows and other callers.
+ * Prefer `kind` from `checkPreauthStatus` / `usePreauthPreview`.
+ */
+const PreauthStatusTag: React.FC<PreauthStatusTagProps> = ({
+  kind,
+  status,
+  preauthCode,
+  loading,
+}) => {
+  if (loading || kind === 'loading') {
+    return <InlineLoading description="" />;
+  }
+
+  switch (kind) {
+    case 'no_token':
+      return (
+        <Tag size="sm" type="red">
+          No claim token
+        </Tag>
+      );
+    case 'finalised':
+      return (
+        <Tag size="sm" type="green" title={preauthCode ? `Code: ${preauthCode}` : undefined}>
+          {preauthCode ? `FINALISED · ${preauthCode}` : 'FINALISED'}
+        </Tag>
+      );
+    case 'pending':
+      return (
+        <Tag
+          size="sm"
+          type={isPreauthNeedsClarification(status ?? '') ? 'magenta' : 'purple'}
+          title={status?.trim() || undefined}
+        >
+          {isPreauthNeedsClarification(status ?? '')
+            ? 'Needs clarification'
+            : status?.trim() || 'Pending'}
+        </Tag>
+      );
+    case 'failed':
+      return (
+        <Tag size="sm" type="red">
+          {status?.trim() || 'Failed'}
+        </Tag>
+      );
+    case 'error':
+      return (
+        <Tag size="sm" type="magenta">
+          Error
+        </Tag>
+      );
+    case 'not_raised':
+    default:
+      return (
+        <Tag size="sm" type="gray">
+          Not raised
+        </Tag>
+      );
+  }
+};
+
+export default PreauthStatusTag;

package/src/billing/dashboard/v3/preauth/preauth-typed-fields.md

@@ -0,0 +1,125 @@
+# Preauth fields currently typed (EMR gap inventory)
+
+Independent checklist per scenario. Excludes data already extracted or inferred (consent/claim token, intervention code, doctor National ID / ID type / regulation body from provider + HWR).
+
+---
+
+## 1. Normal preauth
+
+| Currently typed / uploaded | HIE field(s) |
+| --- | --- |
+| ICD-11 *(if not picking a visit diagnosis)* | `diagnoses[].icd_code` |
+| Unit price *(if bill price missing/wrong)* | `items[].unit_price` |
+| Service start / end *(if defaults need change)* | `service_start`, `service_end` |
+| Provider notification email *(if not from session/HWR)* | `provider_notification_email` |
+| Attachments (generate or upload) | `attachments[]` + files |
+
+No specialty clinical narrative for Normal.
+
+---
+
+## 2. Surgical preauth
+
+Form-backed fields are loaded from the **POC Pre-authorization Form** (encounter type PREAUTHORIZATION) when present — shown read-only. Missing form answers block submit until the chart form is completed.
+
+| Source | HIE field(s) |
+| --- | --- |
+| Form: presenting complaints | `chief_complaint` |
+| Clerk (not on form) | `vital_signs` |
+| Form: HPI | `history_of_present_illness` |
+| Form: general examination | `physical_examination` |
+| Form: investigation report | `investigation_report_details` |
+| Form: anaesthesia | `type_of_anaesthesia` |
+| Form: encounter datetime | `surgery_date` |
+| Form: employment / accident / co-insurance | `is_condition_related_to_employment`, `is_condition_related_to_auto_or_other_accident`, `is_co_insured`, `co_insurance_details` |
+| ICD-11 *(if not from visit diagnosis)* | `diagnoses[].icd_code` |
+| Unit price *(if needed)* | `items[].unit_price` |
+| Service start / end *(if needed)* | `service_start`, `service_end` |
+| Provider email *(if needed)* | `provider_notification_email` |
+| Attachments | `attachments[]` + files |
+
+---
+
+## 3. Imaging preauth
+
+| Currently typed / uploaded | HIE field(s) |
+| --- | --- |
+| Clinical indications *(from clinical-notes obs / Pre-authorization form; read-only)* | `clinical_indications` |
+| ICD-11 *(if not from visit diagnosis)* | `diagnoses[].icd_code` |
+| Unit price *(if needed)* | `items[].unit_price` |
+| Service start / end *(if needed)* | `service_start`, `service_end` |
+| Provider email *(if needed)* | `provider_notification_email` |
+| Attachments | `attachments[]` + files |
+
+---
+
+## 4. Renal preauth
+
+Form-backed dialysis fields come from the **POC Pre-authorization Form** (read-only when present).
+
+| Source | HIE field(s) |
+| --- | --- |
+| Form: session number | `number_of_sessions_required` |
+| Clerk (not on form) | `cost_per_session` |
+| Form: frequency of sessions | `frequency_of_sessions` |
+| Form: clinical indication | `clinical_indications` |
+| Form: start date | `start_date` |
+| Form: co-insured (+ details when yes) | `is_co_insured`, `co_insurance_details` |
+| ICD-11 *(if not from visit diagnosis)* | `diagnoses[].icd_code` |
+| Unit price *(if needed)* | `items[].unit_price` |
+| Service start / end *(if needed)* | `service_start`, `service_end` |
+| Provider email *(if needed)* | `provider_notification_email` |
+| Attachments | `attachments[]` + files |
+
+---
+
+## 5. Oncology preauth
+
+| Currently typed / uploaded | HIE field(s) |
+| --- | --- |
+| Carcinoma staging | `carcinoma_staging` |
+| Comorbidity | `comorbidity` |
+| Metastases | `metastases` |
+| Treatment setting | `treatment_setting` |
+| Number of sessions required | `number_of_sessions_required` |
+| Cost per session | `cost_per_session` |
+| Is co-insured | `is_co_insured` |
+| ICD-11 *(if not from visit diagnosis)* | `diagnoses[].icd_code` |
+| Unit price *(if needed)* | `items[].unit_price` |
+| Service start / end *(if needed)* | `service_start`, `service_end` |
+| Provider email *(if needed)* | `provider_notification_email` |
+| Attachments | `attachments[]` + files |
+| Start date / progress report *(docs; start date not fully separate in current UI)* | `start_date`, `progress_report` |
+
+---
+
+## 6. Optical preauth
+
+| Currently typed / uploaded | HIE field(s) |
+| --- | --- |
+| Necessity of service | `necessity_of_service` |
+| Lens prescription | `lens_prescription` |
+| Lens amount | `lens_amount` |
+| Eye examination amount | `eye_examination_amount` |
+| Frame amount | `frame_amount` |
+| New or replacement | `new_or_replacement` |
+| Clinical indications *(required by HIE; ensure UI captures if not already)* | `clinical_indications` |
+| ICD-11 *(if not from visit diagnosis)* | `diagnoses[].icd_code` |
+| Unit price *(if needed)* | `items[].unit_price` |
+| Service start / end *(if needed)* | `service_start`, `service_end` |
+| Provider email *(if needed)* | `provider_notification_email` |
+| Attachments | `attachments[]` + files |
+
+---
+
+## Already available (excluded from tables above)
+
+- Consent / claim token
+- Intervention code
+- Doctor National ID, ID type, regulation body (OpenMRS provider attribute + HWR)
+
+## References
+
+- [Postman HIE Integrations UAT](https://documenter.getpostman.com/view/39260559/2sB3dSPoWf)
+- [eClaims Preauths API](https://hie-docs.dha.go.ke/eclaims/preauths)
+- [Normal](https://hie-docs.dha.go.ke/docs/claims/process/preauths/normalPreauths) · [Surgical](https://hie-docs.dha.go.ke/docs/claims/process/preauths/surgicalPreauths) · [Imaging](https://hie-docs.dha.go.ke/docs/claims/process/preauths/imagingPreauth) · [Renal](https://hie-docs.dha.go.ke/docs/claims/process/preauths/renalPreauth) · [Oncology](https://hie-docs.dha.go.ke/docs/claims/process/preauths/oncologyPreauth) · [Optical](https://hie-docs.dha.go.ke/docs/claims/process/preauths/opticalPreauth)