@ampath/esm-dha-workflow-app 4.0.0-next.44 → 4.0.0-next.445

package/src/registry/drawer/otp-verification-step.component.tsx

@@ -0,0 +1,398 @@
+import React, { useEffect, useState } from 'react';
+import { Button, Dropdown, RadioButton, RadioButtonGroup, TextInput } from '@carbon/react';
+import { CheckmarkFilled, CheckmarkOutline, Information, Renew, WarningAltFilled } from '@carbon/react/icons';
+import { showSnackbar } from '@openmrs/esm-framework';
+import { OtpOptions, OtpStatus, type RequestCustomOtpDto } from '../types';
+import { requestCustomOtp, validateCustomOtp } from '../registry.resource';
+import { maskAllButFirstAndLastThree, maskPhone } from '../utils/mask-data';
+import { getReadableErrorMessage } from '../utils/error-handler';
+import { formatPhoneNumberForOTP } from '../utils/phone-number-formatter';
+import OTPInput from '../../shared/ui/otp-input/otp-input.component';
+import styles from './workflow-drawer.component.scss';
+
+const formatTime = (s: number) => `${String(Math.floor(s / 60)).padStart(2, '0')}:${String(s % 60).padStart(2, '0')}`;
+
+// Resend becomes available after a short cooldown, separate from the 5-min code expiry.
+const RESEND_COOLDOWN_SECONDS = 30;
+
+// Reasons a worker may need to send the OTP to a number other than the one on
+// record. Presented as an option set when overriding.
+const OVERRIDE_REASONS = [
+  'Registered phone is unreachable',
+  'Wrong number on record',
+  'Patient has no phone',
+  'Using next of kin / guardian phone',
+  'Other',
+];
+
+interface OtpVerificationStepProps {
+  requestCustomOtpDto: RequestCustomOtpDto;
+  phoneNumber: string;
+  onVerified: () => void;
+  timerSeconds?: number;
+  biometricFailedCount?: number;
+}
+
+const OtpVerificationStep: React.FC<OtpVerificationStepProps> = ({
+  requestCustomOtpDto,
+  phoneNumber,
+  onVerified,
+  timerSeconds = 60,
+  biometricFailedCount = 0,
+}) => {
+  const [otp, setOtp] = useState('');
+  const [otpStatus, setOtpStatus] = useState<string>(OtpStatus.Draft);
+  const [loading, setLoading] = useState(false);
+  const [verifying, setVerifying] = useState(false);
+  const [sessionId, setSessionId] = useState('');
+  const [otpAttempt, setOtpAttempt] = useState(0);
+  const [sentTo, setSentTo] = useState('');
+  const [canResend, setCanResend] = useState(false);
+  const [expiresIn, setExpiresIn] = useState(timerSeconds);
+  const [resendIn, setResendIn] = useState(RESEND_COOLDOWN_SECONDS);
+  const [overrideOtp, setOverrideOtp] = useState<OtpOptions>(
+    requestCustomOtpDto.phoneNumber ? OtpOptions.NoOverride : OtpOptions.Override,
+  );
+  const [alternativePhoneNo, setAlternativePhoneNo] = useState<string>();
+  const [overrideReason, setOverrideReason] = useState<string | null>(null);
+  const [phoneError, setPhoneError] = useState('');
+  const [reasonError, setReasonError] = useState('');
+  const [sendError, setSendError] = useState('');
+  const [verifyError, setVerifyError] = useState('');
+
+  const showAlert = (kind: 'error' | 'success', title: string, subtitle: string) =>
+    showSnackbar({ kind, title, subtitle });
+
+  const getOtpPayload = (): RequestCustomOtpDto => {
+    if (overrideOtp === OtpOptions.Override) {
+      // Retain the client's original ID number; only the phone number is overridden.
+      return {
+        ...requestCustomOtpDto,
+        phoneNumber: alternativePhoneNo ? formatPhoneNumberForOTP(alternativePhoneNo) : '',
+      };
+    }
+    return requestCustomOtpDto;
+  };
+
+  // Inline validation for the override (alternative-number) fields.
+  const validateOverride = (): boolean => {
+    let valid = true;
+    const phone = (alternativePhoneNo ?? '').trim();
+    if (!phone) {
+      setPhoneError('Alternative phone number is required');
+      valid = false;
+    } else if (phone.replace(/\D/g, '').length < 9) {
+      setPhoneError('Enter a valid phone number');
+      valid = false;
+    } else {
+      setPhoneError('');
+    }
+    if (!overrideReason) {
+      setReasonError('Select an override reason');
+      valid = false;
+    } else {
+      setReasonError('');
+    }
+    return valid;
+  };
+
+  const handleSendOtp = async () => {
+    // When overriding, the alternative number and a reason are required.
+    if (overrideOtp === OtpOptions.Override) {
+      if (!validateOverride()) {
+        return;
+      }
+    } else if (!requestCustomOtpDto.identificationNumber) {
+      showAlert('error', 'Invalid identification value', 'Please enter a valid ID value');
+      return;
+    }
+    setLoading(true);
+    setSendError('');
+    try {
+      const response = await requestCustomOtp(getOtpPayload());
+      setSessionId(response.sessionId);
+      setSentTo(response.maskedPhone); // shown in-page instead of a toast
+      setCanResend(false); // resend re-enables only once the countdown ends
+      setOtpStatus(OtpStatus.Sent);
+      setOtpAttempt((n) => n + 1); // remount the timer so it restarts from full duration
+    } catch (err: any) {
+      // Surface the failure inline (not just a toast) so the worker can retry in place.
+      const reason = getReadableErrorMessage(err, 'We couldn’t send the OTP. Please retry.');
+      setSendError(reason);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleVerifyOtp = async () => {
+    if (!otp.trim()) {
+      showAlert('error', 'Please enter the OTP code', '');
+      return;
+    }
+    setVerifying(true);
+    setVerifyError('');
+    try {
+      await validateCustomOtp({ sessionId, otp, locationUuid: requestCustomOtpDto.locationUuid });
+      setOtpStatus(OtpStatus.Verified);
+    } catch (err: any) {
+      // Communicate the failure inline so the worker can re-enter the code neatly.
+      const reason = getReadableErrorMessage(err, 'The code couldn’t be verified. Please retry.');
+      setVerifyError(reason);
+    } finally {
+      setVerifying(false);
+    }
+  };
+
+  // Return to the OTP options (where to send / alternative / skip).
+  const backToOptions = () => {
+    setOtp('');
+    setOtpStatus(OtpStatus.Draft);
+  };
+
+  const handleOverrideSelection = (selection: OtpOptions) => {
+    // Skip no longer verifies immediately — the worker must confirm first.
+    setOverrideOtp(selection);
+  };
+
+  const confirmSkip = () => {
+    setOtpStatus(OtpStatus.Verified);
+  };
+
+  // After each send, run two countdowns: the 5-min code expiry and the 30-sec
+  // resend cooldown. Resend enables when the cooldown reaches zero.
+  useEffect(() => {
+    if (otpStatus !== OtpStatus.Sent) {
+      return;
+    }
+    setExpiresIn(timerSeconds);
+    setResendIn(RESEND_COOLDOWN_SECONDS);
+    setCanResend(false);
+    let elapsed = 0;
+    const id = setInterval(() => {
+      elapsed += 1;
+      setExpiresIn(Math.max(0, timerSeconds - elapsed));
+      const remainingResend = Math.max(0, RESEND_COOLDOWN_SECONDS - elapsed);
+      setResendIn(remainingResend);
+      if (remainingResend === 0) {
+        setCanResend(true);
+      }
+      if (elapsed >= timerSeconds) {
+        clearInterval(id);
+      }
+    }, 1000);
+    return () => clearInterval(id);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [otpStatus, otpAttempt]);
+
+  // Let the drawer advance to the next step once verification succeeds.
+  useEffect(() => {
+    if (otpStatus === OtpStatus.Verified) {
+      onVerified();
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [otpStatus]);
+
+  return (
+    <div className={styles.stepContent}>
+      {otpStatus === OtpStatus.Draft ? (
+        <>
+          <div className={styles.infoNote}>
+            <Information size={20} className={styles.infoNoteIcon} />
+            <p className={styles.infoNoteText}>Verify the patient&apos;s identity with a One-Time Password (OTP).</p>
+          </div>
+          {/* Explains why we're on OTP — hidden once the code is sent */}
+          {biometricFailedCount >= 3 ? (
+            <div className={styles.fallbackNote}>
+              <Information size={18} className={styles.fallbackNoteIcon} />
+              <span>Fingerprint failed {biometricFailedCount} times. Verify the patient with an OTP instead.</span>
+            </div>
+          ) : null}
+          <div className={styles.otpChoiceCard}>
+            <RadioButtonGroup
+              orientation="vertical"
+              valueSelected={overrideOtp}
+              legendText="Where should the OTP be sent?"
+              onChange={(v) => handleOverrideSelection(v as OtpOptions)}
+              name="otp-override-group"
+              disabled={loading}
+            >
+              {requestCustomOtpDto?.phoneNumber && (
+                <RadioButton
+                  id="no-override"
+                  labelText={
+                    <span>
+                      Send code to registered phone{' '}
+                      <span className={styles.phoneChip}>{maskAllButFirstAndLastThree(phoneNumber)}</span>
+                    </span>
+                  }
+                  value={OtpOptions.NoOverride}
+                />
+              )}
+              <RadioButton id="override" labelText="Send OTP to an alternative number" value={OtpOptions.Override} />
+              <RadioButton id="skip" labelText="Skip OTP verification" value={OtpOptions.Skip} />
+            </RadioButtonGroup>
+          </div>
+
+          {/* Override: alternative number + reason (an option set) */}
+          {overrideOtp === OtpOptions.Override ? (
+            <div className={styles.overrideFields}>
+              <TextInput
+                id="override-phone"
+                labelText={
+                  <span>
+                    Alternative phone number <span className={styles.required}>*</span>
+                  </span>
+                }
+                value={alternativePhoneNo ?? ''}
+                onChange={(e) => {
+                  setAlternativePhoneNo(e.target.value);
+                  if (phoneError) {
+                    setPhoneError('');
+                  }
+                }}
+                onBlur={validateOverride}
+                invalid={!!phoneError}
+                invalidText={phoneError}
+                placeholder="Enter phone number"
+                disabled={loading}
+              />
+              <Dropdown
+                id="override-reason"
+                titleText={
+                  <span>
+                    Override reason <span className={styles.required}>*</span>
+                  </span>
+                }
+                label="Select a reason"
+                items={OVERRIDE_REASONS}
+                selectedItem={overrideReason}
+                onChange={({ selectedItem }) => {
+                  setOverrideReason(selectedItem as string);
+                  setReasonError('');
+                }}
+                invalid={!!reasonError}
+                invalidText={reasonError}
+                disabled={loading}
+              />
+            </div>
+          ) : (
+            <></>
+          )}
+
+          {/* Skip requires an explicit confirmation */}
+          {overrideOtp === OtpOptions.Skip ? (
+            <>
+              <div className={styles.noticeBox}>
+                <WarningAltFilled size={20} className={styles.noticeIcon} />
+                <div>
+                  <h5 className={styles.noticeTitle}>Skip identity verification?</h5>
+                  <p className={styles.centerText}>
+                    The patient&apos;s identity won&apos;t be confirmed by OTP. Only skip if you have verified them
+                    another way.
+                  </p>
+                </div>
+              </div>
+              <Button kind="danger" size="sm" className={styles.otpPrimaryBtn} onClick={confirmSkip}>
+                Confirm skip
+              </Button>
+            </>
+          ) : (
+            <>
+              {sendError ? (
+                <div className={styles.errorNote}>
+                  <WarningAltFilled size={20} className={styles.errorNoteIcon} />
+                  <p className={styles.errorNoteText}>{sendError} Please try again.</p>
+                </div>
+              ) : null}
+              <Button
+                kind="primary"
+                size="sm"
+                className={styles.otpPrimaryBtn}
+                disabled={
+                  loading ||
+                  (overrideOtp === OtpOptions.Override && (!alternativePhoneNo?.trim() || !overrideReason))
+                }
+                onClick={handleSendOtp}
+              >
+                {loading ? 'Sending OTP…' : sendError ? 'Send OTP again' : 'Send OTP'}
+              </Button>
+            </>
+          )}
+        </>
+      ) : (
+        <></>
+      )}
+
+      {otpStatus === OtpStatus.Sent ? (
+        <div className={styles.otpForm}>
+          {/* Visible confirmation of where the code was sent */}
+          <div className={styles.otpSentBanner}>
+            <CheckmarkFilled size={18} className={styles.otpSentIcon} />
+            <span>
+              A one-time code was sent to <strong>{maskPhone(sentTo)}</strong>. Ask the patient to share it with you.
+            </span>
+          </div>
+
+          <div className={styles.otpEntry}>
+            <span className={styles.otpEntryLabel}>Enter the 5-digit OTP</span>
+            <OTPInput
+              otpLength={5}
+              disabled={verifying || loading}
+              onChange={(value) => {
+                setOtp(value);
+                if (verifyError) {
+                  setVerifyError('');
+                }
+              }}
+            />
+            <span className={styles.otpExpiry}>
+              {expiresIn > 0 ? `Code expires in ${formatTime(expiresIn)}` : 'Code expired'}
+            </span>
+          </div>
+
+          {verifyError ? (
+            <div className={styles.errorNote}>
+              <WarningAltFilled size={20} className={styles.errorNoteIcon} />
+              <div className={styles.errorNoteBody}>
+                <span className={styles.errorNoteTitle}>We couldn&apos;t verify that code</span>
+                <p className={styles.errorNoteText}>{verifyError}</p>
+              </div>
+            </div>
+          ) : null}
+
+          <div className={styles.otpActions}>
+            {/* Resend counts down (30s) and only becomes clickable when it reaches zero */}
+            {canResend ? (
+              <Button kind="ghost" size="sm" renderIcon={Renew} disabled={loading} onClick={handleSendOtp}>
+                {loading ? 'Resending…' : 'Resend code'}
+              </Button>
+            ) : (
+              <span className={styles.resendCountdown}>Resend in {resendIn}s</span>
+            )}
+            <Button
+              kind="primary"
+              size="sm"
+              renderIcon={CheckmarkOutline}
+              disabled={loading || verifying || otp.length !== 5}
+              onClick={handleVerifyOtp}
+            >
+              {verifying ? 'Verifying…' : 'Verify'}
+            </Button>
+          </div>
+
+          {/* Way back to the OTP options if the patient isn't receiving the code */}
+          <p className={styles.otpHelp}>
+            Didn&apos;t receive the code?{' '}
+            <button type="button" className={styles.linkBtn} onClick={backToOptions}>
+              Change how it&apos;s sent
+            </button>
+          </p>
+        </div>
+      ) : (
+        <></>
+      )}
+    </div>
+  );
+};
+
+export default OtpVerificationStep;

package/src/registry/drawer/pomsf-balance.util.test.ts

@@ -0,0 +1,177 @@
+import { type Scheme } from '../types';
+import { type PomsfBalance } from '../../claims';
+import {
+  findPomsfBenefitBalance,
+  formatKes,
+  getAllPomsfBenefitBalances,
+  getPomsfDisplayBalance,
+  isPomsfActive,
+} from './pomsf-balance.util';
+
+function makeScheme(schemeName: string, status: string): Scheme {
+  return {
+    schemeName,
+    memberType: 'BENEFICIARY',
+    coverageType: 'SHIF',
+    policy: { startDate: '', endDate: '', number: '' },
+    coverage: { startDate: '', endDate: '', message: '', reason: '', possibleSolution: null, status },
+    principalContributor: {
+      idNumber: '',
+      name: '',
+      crNumber: '',
+      relationship: '',
+      employmentType: '',
+      employerDetails: undefined,
+    },
+  } as unknown as Scheme;
+}
+
+function makePomsfBalance(
+  benefits: Array<{ benefitCode: string; balance: number | undefined; name?: string }>,
+): PomsfBalance {
+  return {
+    memberPolicies: [
+      {
+        benefit: benefits.map(({ benefitCode, balance, name = '' }) => ({
+          benefitId: 1,
+          name,
+          description: '',
+          type: '',
+          limit: 2000000,
+          benefitShared: null,
+          benefitRelation: null,
+          benefitGender: null,
+          subBenefit: [],
+          balance: balance === undefined ? [] : [{ member: 'self', balance }],
+          benefitCode,
+        })),
+      },
+    ],
+  } as unknown as PomsfBalance;
+}
+
+describe('isPomsfActive', () => {
+  it('is true when a POMSF scheme has coverage status 1', () => {
+    expect(isPomsfActive([makeScheme('POMSF', '1')])).toBe(true);
+  });
+
+  it('is false when POMSF is present but not active', () => {
+    expect(isPomsfActive([makeScheme('POMSF', '0')])).toBe(false);
+  });
+
+  it('is false when POMSF is absent', () => {
+    expect(isPomsfActive([makeScheme('UHC', '1')])).toBe(false);
+  });
+});
+
+describe('findPomsfBenefitBalance', () => {
+  it('finds the balance for a matching benefit code', () => {
+    const pomsfBalance = makePomsfBalance([{ benefitCode: 'PMF-12', balance: 197000 }]);
+    expect(findPomsfBenefitBalance(pomsfBalance, 'PMF-12')).toBe(197000);
+  });
+
+  it('returns null when no benefit line matches the code', () => {
+    const pomsfBalance = makePomsfBalance([{ benefitCode: 'PMF-07', balance: 2000000 }]);
+    expect(findPomsfBenefitBalance(pomsfBalance, 'PMF-12')).toBeNull();
+  });
+
+  it('returns null when the matching benefit has no balance entries', () => {
+    const pomsfBalance = makePomsfBalance([{ benefitCode: 'PMF-12', balance: undefined }]);
+    expect(findPomsfBenefitBalance(pomsfBalance, 'PMF-12')).toBeNull();
+  });
+
+  it('returns null when there is no balance data yet', () => {
+    expect(findPomsfBenefitBalance(null, 'PMF-12')).toBeNull();
+  });
+});
+
+describe('getPomsfDisplayBalance', () => {
+  const pomsfBalance = makePomsfBalance([
+    { benefitCode: 'PMF-07', balance: 2000000 },
+    { benefitCode: 'PMF-12', balance: 197000 },
+  ]);
+
+  it('resolves the Outpatient Services (PMF-12) balance when POMSF is active and Visit type is Outpatient', () => {
+    const schemes = [makeScheme('POMSF', '1')];
+    expect(getPomsfDisplayBalance(schemes, 'Outpatient', pomsfBalance)).toBe(197000);
+  });
+
+  it('resolves the Inpatient Services (PMF-07) balance when POMSF is active and Visit type is Inpatient', () => {
+    const schemes = [makeScheme('POMSF', '1')];
+    expect(getPomsfDisplayBalance(schemes, 'Inpatient', pomsfBalance)).toBe(2000000);
+  });
+
+  it('returns null when POMSF is not Active', () => {
+    const schemes = [makeScheme('POMSF', '0')];
+    expect(getPomsfDisplayBalance(schemes, 'Outpatient', pomsfBalance)).toBeNull();
+  });
+
+  it('returns null when a non-POMSF scheme is Active but POMSF is not present', () => {
+    const schemes = [makeScheme('UHC', '1')];
+    expect(getPomsfDisplayBalance(schemes, 'Outpatient', pomsfBalance)).toBeNull();
+  });
+
+  it('returns null when Visit type has not been picked yet', () => {
+    const schemes = [makeScheme('POMSF', '1')];
+    expect(getPomsfDisplayBalance(schemes, '', pomsfBalance)).toBeNull();
+  });
+
+  it('returns null when no matching benefit line is found in the response', () => {
+    const schemes = [makeScheme('POMSF', '1')];
+    const balanceMissingOutpatient = makePomsfBalance([{ benefitCode: 'PMF-07', balance: 2000000 }]);
+    expect(getPomsfDisplayBalance(schemes, 'Outpatient', balanceMissingOutpatient)).toBeNull();
+  });
+
+  it('still returns 0 (not null) for a zero balance, since it is meaningful to staff', () => {
+    const schemes = [makeScheme('POMSF', '1')];
+    const zeroBalance = makePomsfBalance([{ benefitCode: 'PMF-12', balance: 0 }]);
+    expect(getPomsfDisplayBalance(schemes, 'Outpatient', zeroBalance)).toBe(0);
+  });
+});
+
+describe('getAllPomsfBenefitBalances', () => {
+  it('lists every benefit line with its name, code, and balance', () => {
+    const pomsfBalance = makePomsfBalance([
+      { benefitCode: 'PMF-07', balance: 2000000, name: 'Inpatient Services' },
+      { benefitCode: 'PMF-12', balance: 197000, name: 'Outpatient Services' },
+    ]);
+    expect(getAllPomsfBenefitBalances(pomsfBalance)).toEqual([
+      { code: 'PMF-07', name: 'Inpatient Services', balance: 2000000 },
+      { code: 'PMF-12', name: 'Outpatient Services', balance: 197000 },
+    ]);
+  });
+
+  it('de-duplicates a benefit code that appears under more than one policy', () => {
+    const pomsfBalance = {
+      memberPolicies: [
+        {
+          benefit: [
+            { benefitCode: 'PMF-12', name: 'Outpatient Services', balance: [{ member: 'self', balance: 197000 }] },
+          ],
+        },
+        {
+          benefit: [
+            { benefitCode: 'PMF-12', name: 'Outpatient Services', balance: [{ member: 'self', balance: 500 }] },
+          ],
+        },
+      ],
+    } as unknown as PomsfBalance;
+    expect(getAllPomsfBenefitBalances(pomsfBalance)).toEqual([
+      { code: 'PMF-12', name: 'Outpatient Services', balance: 197000 },
+    ]);
+  });
+
+  it('returns an empty list when there is no balance data yet', () => {
+    expect(getAllPomsfBenefitBalances(null)).toEqual([]);
+  });
+});
+
+describe('formatKes', () => {
+  it('formats a positive amount with thousands separators and two decimals', () => {
+    expect(formatKes(197000)).toBe('KES 197,000.00');
+  });
+
+  it('formats a zero balance explicitly', () => {
+    expect(formatKes(0)).toBe('KES 0.00');
+  });
+});

package/src/registry/drawer/pomsf-balance.util.ts

@@ -0,0 +1,116 @@
+import { type Scheme } from '../types';
+import { type PomsfBalance } from '../../claims';
+import { getHieBaseUrl } from '../../claims/utils';
+import { openmrsFetch } from '@openmrs/esm-framework';
+
+// POMSF's balance is split across two benefit lines by care setting: PMF-07 is
+// Inpatient Services, PMF-12 is Outpatient Services. The registration form only
+// captures Visit type (Outpatient/Inpatient), so that's the only signal available
+// to decide which line's balance to surface.
+const POMSF_BENEFIT_CODE_BY_VISIT_TYPE: Record<string, string> = {
+  Outpatient: 'PMF-12',
+  Inpatient: 'PMF-07',
+};
+
+export function isPomsfActive(schemes: Scheme[]): boolean {
+  const pomsfScheme = schemes.find((s) => /^(pomsf(?:[-\s].*)?|usalama|tsc)$/i.test(s.schemeName.trim()));
+  return !!pomsfScheme && pomsfScheme.coverage?.status === '1';
+}
+
+export function findPomsfBenefitBalance(
+  pomsfBalance: PomsfBalance | null | undefined,
+  benefitCode: string | null,
+): number | null {
+  if (!pomsfBalance || !benefitCode) {
+    return null;
+  }
+  for (const memberPolicy of pomsfBalance.memberPolicies ?? []) {
+    const benefit = memberPolicy.benefit?.find((b) => b.benefitCode === benefitCode);
+    if (benefit) {
+      return benefit.balance?.[0]?.balance ?? null;
+    }
+  }
+  return null;
+}
+
+// Resolves the balance for the current Visit type, or null if nothing should
+// render (POMSF isn't Active, Visit type isn't picked yet, or no matching
+// benefit line exists in the response). Deliberately independent of which
+// scheme is selected in the Insurance scheme dropdown — the Eligibility row
+// lists every active scheme regardless of selection (see workflow-drawer),
+// so this resolves once POMSF is Active and callers decide where to show it.
+export function getPomsfDisplayBalance(
+  schemes: Scheme[],
+  visitType: string,
+  pomsfBalance: PomsfBalance | null | undefined,
+): number | null {
+  if (!isPomsfActive(schemes)) {
+    return null;
+  }
+  const benefitCode = POMSF_BENEFIT_CODE_BY_VISIT_TYPE[visitType] ?? null;
+  return findPomsfBenefitBalance(pomsfBalance, benefitCode);
+}
+
+export function formatKes(amount: number): string {
+  return `KES ${amount.toLocaleString('en-KE', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+
+export interface PomsfBenefitBalance {
+  code: string;
+  name: string;
+  balance: number | null;
+}
+
+// Every benefit line in the /pomsf-balance response (not just the one matching
+// the current Visit type), for showing the full breakdown. De-duplicated by
+// benefit code in case the same benefit appears under more than one policy.
+export function getAllPomsfBenefitBalances(pomsfBalance: PomsfBalance | null | undefined): PomsfBenefitBalance[] {
+  const byCode = new Map<string, PomsfBenefitBalance>();
+  for (const memberPolicy of pomsfBalance?.memberPolicies ?? []) {
+    for (const benefit of memberPolicy.benefit ?? []) {
+      if (!byCode.has(benefit.benefitCode)) {
+        byCode.set(benefit.benefitCode, {
+          code: benefit.benefitCode,
+          name: benefit.name,
+          balance: benefit.balance?.[0]?.balance ?? null,
+        });
+      }
+    }
+  }
+  return Array.from(byCode.values());
+}
+
+export type PomsfCoveragePayload = {
+  principalCrId: string;
+  consentToken: string;
+  policyNumber: string;
+  locationUuid: string;
+};
+
+export async function setEffectiveCoverage(payload: PomsfCoveragePayload): Promise<any> {
+  const { hieBaseUrl } = await getHieBaseUrl();
+
+  const url = `${hieBaseUrl}/pomsf/set-effective-coverage`;
+  const response = await openmrsFetch(url, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(payload),
+  });
+
+  const data = await response.json();
+
+  if (!response.ok) {
+    const errorText = data.message || 'Failed to set effective coverage';
+
+    return {
+      success: false,
+      status: response.status,
+      message: errorText,
+    };
+  }
+
+  return data;
+}