@ampath/esm-dha-workflow-app 4.0.0-claim-workflows.310 → 4.0.0-claim-workflows.312

package/src/billing/dashboard/v3/claim-visits/claim-intervention-details/claim-intervention-details.component.tsx

@@ -1,34 +1,52 @@
 import React from 'react';
 import { type PatientFacilityBillDetails, type VisitIntervention } from '../../types';
-import { Button, ButtonSet, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, Tag } from '@carbon/react';
+import {
+  MenuButton,
+  MenuItem,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+  Tag,
+} from '@carbon/react';
 import { launchWorkspace, showSnackbar, useSession } from '@openmrs/esm-framework';
 
-import styles from './claim-intervention-details.component.scss';
 import { invalidatePreauthPreview, parseDocTypes, readSpecialtyFlags } from '../../../v2/preauth/preauth.resource';
+import {
+  interventionHasBlockingPreauth,
+  interventionHasFailedPreauth,
+  usePreauthPreview,
+} from '../../../../../claims/claims.resource';
 
 interface claimInterventionDetailsProps {
   claimInterventions: VisitIntervention[];
   patientBillDetails: PatientFacilityBillDetails;
   consentToken: string;
   visitUuid: string;
+  canSwitchIntervention?: boolean;
+  onSwitchSuccess?: () => void;
 }
+
+const isActiveIntervention = (iv: VisitIntervention) => (iv.workflow_state ?? '').toUpperCase() === 'ACTIVE';
+
 const ClaimInterventionDetails: React.FC<claimInterventionDetailsProps> = ({
   claimInterventions,
   patientBillDetails,
   consentToken,
   visitUuid,
+  canSwitchIntervention = false,
+  onSwitchSuccess,
 }) => {
+  const session = useSession();
+  const locationUuid = session?.sessionLocation?.uuid;
+  const { preview: preauthPreview } = usePreauthPreview(consentToken, locationUuid);
+
   if (!claimInterventions || claimInterventions.length === 0) {
     return <>No Intervention data</>;
   }
-  function formatPreAuthText(preAuth: boolean) {
-    if (preAuth) {
-      return 'YES';
-    }
-    return 'NO';
-  }
-  const session = useSession();
-  const locationUuid = session?.sessionLocation?.uuid;
+
   const handleAddAttachment = (ci: any) => {
     launchWorkspace('upload-intervention-attachments-workspace', {
       consentToken: consentToken,
@@ -44,10 +62,31 @@ const ClaimInterventionDetails: React.FC<claimInterventionDetailsProps> = ({
       bill: patientBillDetails,
     });
   };
+
+  const canActOnIntervention = (intervention: VisitIntervention) =>
+    canSwitchIntervention && isActiveIntervention(intervention);
+
+  const hasBlockingPreauth = (intervention: VisitIntervention) =>
+    interventionHasBlockingPreauth(preauthPreview, intervention.intervention_code);
+
+  /** Switch stays locked while a non-resubmittable preauth is in flight / finalised. */
+  const canSwitchFor = (intervention: VisitIntervention) =>
+    canActOnIntervention(intervention) && !hasBlockingPreauth(intervention);
+
+  const canRaisePreauthFor = (intervention: VisitIntervention) => {
+    return canActOnIntervention(intervention) && Boolean(intervention.needs_preauth) && !hasBlockingPreauth(intervention);
+  };
+
+  const isResubmitPreauth = (intervention: VisitIntervention) =>
+    interventionHasFailedPreauth(preauthPreview, intervention.intervention_code);
+
+  const raisePreauthLabel = (intervention: VisitIntervention) =>
+    isResubmitPreauth(intervention) ? 'Resubmit preauth' : 'Raise preauth';
+
   const handleSwitchIntervention = (intervention: VisitIntervention) => {
-    // if (!canSwitchIntervention) {
-    //   return;
-    // }
+    if (!canSwitchFor(intervention)) {
+      return;
+    }
     launchWorkspace('switch-intervention-workspace', {
       consentToken: consentToken,
       currentInterventions: [intervention],
@@ -56,16 +95,14 @@ const ClaimInterventionDetails: React.FC<claimInterventionDetailsProps> = ({
       visitUuid: visitUuid,
       billDate: patientBillDetails?.bill_date,
       onSwitchSuccess: () => {
-        // invalidateProviderClaimPreview();
+        onSwitchSuccess?.();
       },
     });
   };
-
   const handleRaisePreauth = (intervention: VisitIntervention) => {
-    // if (!canSwitchIntervention) {
-    //   return;
-    // }
-    // const consentToken = claimsVisit.authorization_code;
+    if (!canSwitchIntervention) {
+      return;
+    }
     if (!consentToken) {
       showSnackbar({
         kind: 'error',
@@ -74,9 +111,9 @@ const ClaimInterventionDetails: React.FC<claimInterventionDetailsProps> = ({
       });
       return;
     }
-    // if (!intervention.needs_preauth) {
-    //   return;
-    // }
+    if (!canRaisePreauthFor(intervention)) {
+      return;
+    }
 
     const requiredDocs = parseDocTypes(
       Array.isArray(intervention.required_preauth_document_types)
@@ -87,6 +124,7 @@ const ClaimInterventionDetails: React.FC<claimInterventionDetailsProps> = ({
       ? intervention.applicable_document_types.map(String)
       : parseDocTypes(intervention.applicable_document_types as string | null | undefined);
 
+    // Fresh raise and failure-state resubmit both reopen the same preauth form.
     launchWorkspace('preauth-form-workspace', {
       consentToken,
       patientUuid: patientBillDetails?.patient_uuid,
@@ -110,10 +148,11 @@ const ClaimInterventionDetails: React.FC<claimInterventionDetailsProps> = ({
       },
       onSuccess: async () => {
         await invalidatePreauthPreview(consentToken, locationUuid!);
-        // invalidateProviderClaimPreview();
+        onSwitchSuccess?.();
       },
     });
   };
+
   return (
     <>
       <Table size="sm">
@@ -133,55 +172,45 @@ const ClaimInterventionDetails: React.FC<claimInterventionDetailsProps> = ({
         </TableHead>
         <TableBody>
           {claimInterventions &&
-            claimInterventions.map((ci, index) => {
+            claimInterventions.map((ci) => {
+              const canSwitch = canSwitchFor(ci);
+              const canRaise = canRaisePreauthFor(ci);
+              const hasAttachments = (ci.applicable_document_types ?? []).length > 0;
               return (
-                <>
-                  <TableRow key={ci.id}>
-                    <TableCell>{ci.intervention_code}</TableCell>
-                    <TableCell>{ci.intervention_payment_mechanism}</TableCell>
-                    <TableCell>{ci.intervention_name}</TableCell>
-                    <TableCell>{ci.accrued_per_diem_amount}</TableCell>
-                    <TableCell>{ci.accrued_per_diem_days}</TableCell>
-                    <TableCell>{ci.workflow_state}</TableCell>
-                    <TableCell>{ci.sub_benefit_code}</TableCell>
-                    <TableCell>{ci.intervention_fund}</TableCell>
-                    <TableCell>
-                      {ci.applicable_document_types.length > 0 ? (
-                        <div className={styles.attachmentButtons}>
-                          <Button kind="primary" size="sm" onClick={() => handleGenerateAttachment(ci)}>
-                            Generate
-                          </Button>
-
-                          <Button kind="primary" size="sm" onClick={() => handleAddAttachment(ci)}>
-                            Upload
-                          </Button>
-                        </div>
-                      ) : (
-                        <Tag type="gray">Not Required</Tag>
-                      )}
-                    </TableCell>
-                    <TableCell>
-                      <div className={styles.attachmentButtons}>
-                        <Button
-                          size="sm"
-                          onClick={() => {
-                            handleRaisePreauth(ci);
-                          }}
-                        >
-                          Raise preauth
-                        </Button>
-                        <Button
-                          size="sm"
-                          onClick={() => {
-                            handleSwitchIntervention(ci);
-                          }}
-                        >
-                          Switch intervention
-                        </Button>
-                      </div>
-                    </TableCell>
-                  </TableRow>
-                </>
+                <TableRow key={ci.id}>
+                  <TableCell>{ci.intervention_code}</TableCell>
+                  <TableCell>{ci.intervention_payment_mechanism}</TableCell>
+                  <TableCell>{ci.intervention_name}</TableCell>
+                  <TableCell>{ci.accrued_per_diem_amount}</TableCell>
+                  <TableCell>{ci.accrued_per_diem_days}</TableCell>
+                  <TableCell>{ci.workflow_state}</TableCell>
+                  <TableCell>{ci.sub_benefit_code}</TableCell>
+                  <TableCell>{ci.intervention_fund}</TableCell>
+                  <TableCell>
+                    {hasAttachments ? (
+                      <MenuButton label="Attachments" kind="ghost" size="sm">
+                        <MenuItem label="Generate" onClick={() => handleGenerateAttachment(ci)} />
+                        <MenuItem label="Upload" onClick={() => handleAddAttachment(ci)} />
+                      </MenuButton>
+                    ) : (
+                      <Tag type="gray">Not Required</Tag>
+                    )}
+                  </TableCell>
+                  <TableCell>
+                    <MenuButton label="Actions" kind="ghost" size="sm">
+                      <MenuItem
+                        label={raisePreauthLabel(ci)}
+                        onClick={() => handleRaisePreauth(ci)}
+                        disabled={!canRaise}
+                      />
+                      <MenuItem
+                        label="Switch intervention"
+                        onClick={() => handleSwitchIntervention(ci)}
+                        disabled={!canSwitch}
+                      />
+                    </MenuButton>
+                  </TableCell>
+                </TableRow>
               );
             })}
         </TableBody>

package/src/billing/dashboard/v3/claim-visits/claim-visit-details/claim-visit-details.component.tsx

@@ -14,17 +14,23 @@ import ClaimDoctors from '../claim-doctors/claim-doctors';
 import AddClaimDoctorModal from '../modal/claim-doctors/add-claim-doctor/add-claim-doctor.modal';
 import { VisitTypeUuids } from '../../../../../shared/constants/visit-types';
 import { VisitType } from '../../../../../claims';
+import { canEditClaimContent } from '../../../v2/claim-statuses';
+import { interventionHasBlockingPreauth, usePreauthPreview } from '../../../../../claims/claims.resource';
+
 interface claimVisitDetailsProps {
   claimsVisit: ClaimsVisit;
   locationUuid: string;
   patientBillDetails?: PatientFacilityBillDetails;
   onBillDetailsChange?: () => void;
+  /** True while claim preview is revalidating — stand down content edits. */
+  claimRefreshing?: boolean;
 }
 const ClaimVisitDetails: React.FC<claimVisitDetailsProps> = ({
   claimsVisit,
   locationUuid,
   patientBillDetails,
   onBillDetailsChange,
+  claimRefreshing = false,
 }) => {
   const [showCloseClaimModal, setShowCloseClaimModal] = useState<boolean>();
   const [showSubmitClaimModal, setSubmitCloseClaimModal] = useState<boolean>(false);
@@ -76,6 +82,7 @@ const ClaimVisitDetails: React.FC<claimVisitDetailsProps> = ({
   }, [activeVisit, VisitTypeUuids]);
 
   const invalidateProviderClaimPreview = useInvalidateProviderClaimPreview();
+  const { preview: preauthPreview } = usePreauthPreview(claimsVisit?.authorization_code, locationUuid);
 
   if (!claimsVisit) {
     return <>No Data</>;
@@ -127,7 +134,21 @@ const ClaimVisitDetails: React.FC<claimVisitDetailsProps> = ({
     });
   };
 
+  // Same gates as v2: content edits only while claim is DRAFT / DRAFT_RESUBMIT and not refreshing.
+  const canSwitchIntervention = canEditClaimContent(claimsVisit.workflow_state) && !claimRefreshing;
+  const hasSwitchableIntervention = Boolean(
+    claimsVisit.interventions?.some((iv) => {
+      const active = (iv.workflow_state ?? '').toUpperCase() === 'ACTIVE';
+      if (!active) return false;
+      // Match row Actions: blocking preauth locks Switch together with Raise/Resubmit.
+      return !interventionHasBlockingPreauth(preauthPreview, iv.intervention_code);
+    }),
+  );
+
   const handleSwitchIntervention = () => {
+    if (!canSwitchIntervention || !hasSwitchableIntervention) {
+      return;
+    }
     launchWorkspace('switch-intervention-workspace', {
       consentToken: claimsVisit.authorization_code,
       currentInterventions: claimsVisit.interventions,
@@ -158,7 +179,7 @@ const ClaimVisitDetails: React.FC<claimVisitDetailsProps> = ({
             <Button
               kind="tertiary"
               onClick={handleSwitchIntervention}
-              disabled={!claimsVisit.interventions?.some((iv) => (iv.workflow_state ?? '').toUpperCase() === 'ACTIVE')}
+              disabled={!canSwitchIntervention || !hasSwitchableIntervention}
             >
               Switch Intervention
             </Button>
@@ -231,6 +252,11 @@ const ClaimVisitDetails: React.FC<claimVisitDetailsProps> = ({
                   claimInterventions={claimsVisit.interventions}
                   consentToken={claimsVisit.authorization_code}
                   visitUuid={activeVisit?.uuid}
+                  canSwitchIntervention={canSwitchIntervention}
+                  onSwitchSuccess={() => {
+                    invalidateProviderClaimPreview();
+                    onBillDetailsChange?.();
+                  }}
                 />
               )}
             </div>

package/src/billing/dashboard/v3/patient-bill-details/bill-details/bill-details.tsx

@@ -195,6 +195,7 @@ const BillDetails: React.FC<billDetailsProps> = ({ patientBillDetails, patientPa
            onClose={handleCloseAddClaimItemModal}
            onSuccess={onSuccess}
            locationUuid={locationUuid}
+           consentToken={consentToken}
           />
         }
       </div>

package/src/billing/dashboard/v3/patient-bill-details/claim-details/patient-claim-details.component.tsx

@@ -50,6 +50,7 @@ const PatientClaimDetails: React.FC<patientClaimDetailsProps> = ({
             claimsVisit={claimVisit}
             locationUuid={locationUuid}
             onBillDetailsChange={onBillDetailsChange}
+            claimRefreshing={isValidating}
           />
         )
       }

package/src/billing/dashboard/v3/patient-bill-details/modals/add-claim-line/add-claim-line.modal.tsx

@@ -11,8 +11,16 @@ interface addClaimLineModalProps {
   onSuccess: () => void;
   billItem: PatientFacilityBillDetails;
   locationUuid: string;
+  consentToken?: string;
 }
-const AddClaimLineModal: React.FC<addClaimLineModalProps> = ({ open, onClose, onSuccess, billItem, locationUuid }) => {
+const AddClaimLineModal: React.FC<addClaimLineModalProps> = ({
+  open,
+  onClose,
+  onSuccess,
+  billItem,
+  locationUuid,
+  consentToken: consentTokenProp,
+}) => {
    const [loading,setLoading] = useState<boolean>(false);
   async function handleAddClaimLineItem() {
     setLoading(true);
@@ -46,7 +54,7 @@ const AddClaimLineModal: React.FC<addClaimLineModalProps> = ({ open, onClose, on
   }
   function getClaimLineDto(): AddClaimLineDto {
     return {
-      consentToken: billItem.consent_token,
+      consentToken: (consentTokenProp || billItem.consent_token || '').trim(),
       interventionCode: billItem.intervention_code,
       unitPrice: String(billItem.item_price),
       quantity: String(billItem.item_quantity),

package/src/billing/dashboard/v3/patient-bill-details/patient-bill-details.tsx

@@ -18,6 +18,7 @@ import { Tab, TabList, TabPanel, TabPanels, Tabs } from '@carbon/react';
 import BillDetails from './bill-details/bill-details';
 import PatientClaimDetails from './claim-details/patient-claim-details.component';
 import { type AmrsVisitDiagnosisDto, type AmrsVisitDiagnosis,type AmrsMaternityDiagnosisDto } from '../../../types';
+import { resolveConsentTokenFromBillLines } from '../../v2/patient-bill-details/payment-mode';
 interface patientBillDetailsProps {
   patientUuid: string;
   locationUuid: string;
@@ -60,7 +61,7 @@ const PatientBillDetails: React.FC<patientBillDetailsProps> = ({ patientUuid, lo
       const data = await fetchPatientFacilityBillDetails(patientBillPayload);
       if (data) {
         setPatientBillDetails(data);
-        setConsentToken(data[0].consent_token);
+        setConsentToken(resolveConsentTokenFromBillLines(data));
       }
     } catch (error) {
       showSnackbar({

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

@@ -15,6 +15,7 @@ import { launchWorkspace, showSnackbar } from '@openmrs/esm-framework';
 import {
   checkPreauthStatus,
   invalidatePreauthPreview,
+  isPreauthNeedsClarification,
   type PreauthCheckKind,
 } from '../../../../claims/claims.resource';
 import EmptyState from '../shared/empty-state.component';
@@ -222,12 +223,14 @@ const PreauthList: React.FC<PreauthListProps> = ({ locationUuid, billingDate, on
               const flags = interventionFlagsFromBillItem(item);
               const meta = rowMeta[key];
               const elective = needsElectivePreauth(item);
-              // Already-raised (pending / clarification / finalised) must not show Raise again.
+              // 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()) && !canRaise;
+              const showNotes = Boolean(meta?.notes?.trim()) && meta?.kind !== 'not_raised';
               return (
                 <TableRow key={key}>
                   <TableCell>
@@ -257,7 +260,9 @@ const PreauthList: React.FC<PreauthListProps> = ({ locationUuid, billingDate, on
                   <TableCell>
                     {canRaise ? (
                       <Button kind="ghost" size="sm" onClick={() => handleRaise(item)}>
-                        Raise preauth
+                        {meta?.kind === 'failed' || isPreauthNeedsClarification(meta?.status ?? '')
+                          ? 'Resubmit preauth'
+                          : 'Raise preauth'}
                       </Button>
                     ) : (
                       '—'

package/src/billing/dashboard/v3/preauth/preauth.resource.ts

@@ -1060,6 +1060,11 @@ export {
   usePreauthPreview,
   isPreauthFinalised,
   isPreauthTerminalFailure,
+  isPreauthNeedsClarification,
+  isPreauthResubmittable,
+  interventionHasBlockingPreauth,
+  interventionHasFailedPreauth,
+  interventionAllowsPreauthResubmit,
   invalidatePreauthPreview,
   preauthPreviewSwrKey,
   type PreauthCheckKind,

package/src/billing/dashboard/v3/preauth/preauth.workspace.tsx

@@ -27,7 +27,7 @@ import {
   type PreauthFormPayload,
 } from '../../../../claims/claims.resource';
 import { cancelAllPendingAuthorizations, sendClaimsOTP, authorizeClaimsWithOtp } from '../../../../registry/hie.resource';
-import { addClaimDiagnosis, fetchPatientDiagnosesForBilling } from '../../../billing-claims.resource';
+import { addClaimDiagnosis, fetchPatientDiagnosesForBilling, preferredDiagnosisForPreauth } from '../../../billing-claims.resource';
 import { ensureInterventionOnVisit } from '../../../../claims/interventions.resource';
 import { type AmrsVisitDiagnosis } from '../../../types';
 import { type PatientFacilityBillDetails } from '../types';
@@ -75,7 +75,9 @@ const diagnosisPickLabel = (item: DiagnosisPick | null) => {
   if (!item) return '';
   if (item.kind === 'visit') {
     const d = item.dx;
-    return `${d.icd11_code ?? '—'} · ${d.concept_source_name || d.encounter_type || 'Visit diagnosis'}`;
+    const rank =
+      d.dx_rank != null && Number.isFinite(Number(d.dx_rank)) ? ` · Rank ${Number(d.dx_rank)}` : '';
+    return `${d.icd11_code ?? '—'} · ${d.concept_source_name || d.encounter_type || 'Visit diagnosis'}${rank}`;
   }
   return `${item.hit.icd11Code} · ${item.hit.display}`;
 };
@@ -428,9 +430,11 @@ const PreauthForm: React.FC<PreauthWorkspaceProps> = ({
         });
         if (!cancelled) {
           setVisitDiagnoses(results ?? []);
-          const withIcd = (results ?? []).filter((d) => d.icd11_code);
-          if (withIcd.length === 1) {
-            applyDiagnosisPick(visitDxPick(withIcd[0]), { fromUser: false });
+          // Prefer dx_rank === 1; otherwise best-ranked ICD-coded row. Multiple options
+          // stay available in the ComboBox (already ordered by rank from the fetch).
+          const preferred = preferredDiagnosisForPreauth(results ?? []);
+          if (preferred) {
+            applyDiagnosisPick(visitDxPick(preferred), { fromUser: false });
           }
         }
       } catch {
@@ -1231,7 +1235,7 @@ const PreauthForm: React.FC<PreauthWorkspaceProps> = ({
 
           <div className={styles.searchBlock}>
             <p className={styles.fieldHint}>
-              Diagnosis (ICD-11)
+              Diagnosis (ICD-11). Prefills rank 1 when available; choose another if needed.
             </p>
             {loadingDx ? (
               <InlineLoading description="Loading patient diagnoses…" />

package/src/billing/types/index.ts

@@ -93,6 +93,11 @@ export type AmrsVisitDiagnosis = {
   value_coded?: number | null;
   /** Encounter diagnosis coded concept (/patient/encounter-diagnosis). */
   diagnosis_coded?: number | null;
+  /**
+   * Diagnosis rank from encounter-diagnosis ETL (1 = primary / preferred for preauth).
+   * Lower ranks are preferred when multiple diagnoses are present.
+   */
+  dx_rank?: number | null;
   concept_source_name: string;
   hl7_code: string;
   icd11_code: string;

package/src/claims/claims.resource.ts

@@ -876,7 +876,7 @@ export async function fetchPreauthPreviewRowsForTokens(
   return rows;
 }
 
-const PREAUTH_TERMINAL_FAILURE = new Set(['REJECTED', 'CANCELLED', 'FAILED', 'DECLINED']);
+const PREAUTH_TERMINAL_FAILURE = new Set(['REJECTED', 'CANCELLED', 'CANCELED', 'FAILED', 'DECLINED']);
 
 const PREAUTH_SUBMITTED = new Set([
   'ACTIVE',
@@ -960,15 +960,33 @@ export function extractPreauthCodeForIntervention(
 }
 
 /**
- * True when preview already has a non-failed preauth for this intervention —
- * Raise should be hidden (re-raise allowed after terminal failure).
+ * True when preview already has a non-failed, non-clarification preauth for this
+ * intervention — Raise should be hidden. Terminal failure and clarification allow
+ * reopening the form to resubmit.
  */
 export function interventionHasBlockingPreauth(preview: unknown, interventionCode: string): boolean {
   const item = findPreauthPreviewForIntervention(preview, interventionCode);
   if (!item) return false;
   const status = statusFromPreviewItem(item);
   if (!status) return true; // row exists but status blank — treat as already raised
-  return !isPreauthTerminalFailure(status);
+  return !isPreauthResubmittable(status);
+}
+
+/**
+ * True when this intervention's preauth failed or needs clarification —
+ * UI can offer Resubmit and reopen the preauth form.
+ */
+export function interventionHasFailedPreauth(preview: unknown, interventionCode: string): boolean {
+  const status = extractPreauthStatusForIntervention(preview, interventionCode);
+  return Boolean(status) && isPreauthResubmittable(status);
+}
+
+/** Alias for clarity at call sites that mean "resubmit", not only hard failure. */
+export function interventionAllowsPreauthResubmit(
+  preview: unknown,
+  interventionCode: string,
+): boolean {
+  return interventionHasFailedPreauth(preview, interventionCode);
 }
 
 export function extractPreauthStatus(preview: unknown): string {
@@ -1014,7 +1032,15 @@ export function isPreauthFinalised(status: string): boolean {
 }
 
 export function isPreauthTerminalFailure(status: string): boolean {
-  return PREAUTH_TERMINAL_FAILURE.has((status || '').toUpperCase());
+  const s = (status || '').toUpperCase();
+  if (PREAUTH_TERMINAL_FAILURE.has(s)) return true;
+  // HIE sometimes returns prefixed / alternate spellings (e.g. PREAUTH_CANCELLED).
+  return s.includes('CANCEL');
+}
+
+/** Failure, cancellation, or clarification — provider may reopen the preauth form and resubmit. */
+export function isPreauthResubmittable(status: string): boolean {
+  return isPreauthTerminalFailure(status) || isPreauthNeedsClarification(status);
 }
 
 /** Statuses that mean the preauth was accepted by HIE — form can close. */
@@ -1085,7 +1111,8 @@ export async function checkPreauthStatus(
     if (isPreauthTerminalFailure(status)) {
       return { status, preview, kind: 'failed', preauthCode, notes };
     }
-    // Includes CLARIFICATION_AFTER_AUTOMATIC_CHECKS and other in-flight payer states.
+    // Clarification stays `pending` for status-tag colouring ("Needs clarification"),
+    // but is not a blocking preauth — callers use isPreauthNeedsClarification / resubmit helpers.
     return { status, preview, kind: 'pending', preauthCode, notes };
   } catch (e: unknown) {
     const message = e instanceof Error ? e.message : String(e ?? 'Failed to get preauth preview');