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

package/src/emt/emt.resource.test.ts

@@ -0,0 +1,247 @@
+/**
+ * Tests for the EMT resource layer: fetchPendingReferrals, initiateHandover,
+ * verifyHandoverOtp, and normalizeError.
+ *
+ * We mock `../shared/utils/get-base-url` (`getHieBaseUrl`) and
+ * `@openmrs/esm-framework` (`openmrsFetch`) directly since `emt.resource.ts`
+ * calls them — this avoids loading the heavy OpenMRS module graph.
+ */
+jest.mock('../shared/utils/get-base-url', () => ({
+  getHieBaseUrl: jest.fn(),
+}));
+
+jest.mock('@openmrs/esm-framework', () => ({
+  openmrsFetch: jest.fn(),
+}));
+
+import { openmrsFetch } from '@openmrs/esm-framework';
+import { getHieBaseUrl } from '../shared/utils/get-base-url';
+import {
+  fetchPendingReferrals,
+  initiateHandover,
+  verifyHandoverOtp,
+  normalizeError,
+  getHandoverRequestId,
+} from './emt.resource';
+import { EmtApiError } from './types/emt.types';
+
+const mockOpenmrsFetch = jest.mocked(openmrsFetch);
+const mockGetHieBaseUrl = jest.mocked(getHieBaseUrl);
+
+const BASE_URL = 'http://localhost:3000';
+
+const referralFixture = {
+  submission_id: 3,
+  cr_id: 'CR5617849204955-8',
+  status: 'pending_acceptance',
+  incident_id: 'INC-20260803100645-254727092999-ffjotq',
+  dispatch_id: 'd22419d8-6d36-4b2f-a33c-3e008bd85f77',
+  case_number: 'AMB-d22419d8-6d36-4b2f-a33c-3e008bd85f77-FAC',
+  ambulance_fr_code: 'FID-AMB-916293-3',
+  ambulance_registration_number: 'KDN 085T',
+  facility_fr_code: 'FID-47-108521-3',
+  evacuation_scene: '',
+  priority: 'p1 life threatening (als) with altered consciousness',
+  referral_reason: '',
+  referral_category: '',
+  transport_modality: '',
+  referral_notes: 'Chief complaint: Test.',
+  bundle_id: 'd22419d8-6d36-4b2f-a33c-3e008bd85f77',
+  interventions: ['SHA-01-001'],
+  requested_at: '2026-08-04T09:37:39.438967Z',
+  updated_at: '2026-08-04T09:37:40.428903Z',
+};
+
+const listFixture = {
+  results: [referralFixture],
+  count: 1,
+  limit: 50,
+  offset: 0,
+};
+
+/** Mimics what `openmrsFetch` actually throws for a non-2xx response. */
+function fetchError(status: number, message = `Server responded with ${status}`) {
+  return { response: { status }, message };
+}
+
+beforeEach(() => {
+  jest.resetAllMocks();
+  mockGetHieBaseUrl.mockResolvedValue(BASE_URL);
+});
+
+// ── fetchPendingReferrals ─────────────────────────────────────────────
+
+describe('fetchPendingReferrals', () => {
+  it('requests the referrals endpoint with limit, offset, and the facility locationUuid', async () => {
+    mockOpenmrsFetch.mockResolvedValueOnce({ data: listFixture } as any);
+
+    const data = await fetchPendingReferrals(50, 0, 'location-uuid-1');
+
+    expect(mockOpenmrsFetch).toHaveBeenCalledWith(
+      `${BASE_URL}/emt/referrals?limit=50&offset=0&locationUuid=location-uuid-1`,
+      { method: 'GET' },
+    );
+    expect(data.results).toHaveLength(1);
+    expect(data.results[0].cr_id).toBe('CR5617849204955-8');
+    expect(data.count).toBe(1);
+  });
+
+  it('normalises a malformed envelope gracefully', async () => {
+    mockOpenmrsFetch.mockResolvedValueOnce({ data: { results: undefined, count: 'bad' } } as any);
+
+    const data = await fetchPendingReferrals(undefined, undefined, 'location-uuid-1');
+    expect(data.results).toEqual([]);
+    expect(data.count).toBe(0);
+  });
+
+  it('re-throws as an EmtApiError carrying the real HTTP status', async () => {
+    mockOpenmrsFetch.mockRejectedValueOnce(fetchError(401, 'Token expired'));
+
+    await expect(fetchPendingReferrals()).rejects.toMatchObject({ status: 401 });
+  });
+});
+
+// ── initiateHandover ───────────────────────────────────────────────────
+
+describe('initiateHandover', () => {
+  it('POSTs to /handover/initiate with the request body', async () => {
+    const responseFixture = { request_id: '82fd22b6-e366-4077-9866-e1c4ed7328b0' };
+    mockOpenmrsFetch.mockResolvedValueOnce({ data: responseFixture } as any);
+
+    const res = await initiateHandover({
+      incidenceNumber: 'AMB-d22419d8-FAC',
+      identifier: 'A13579',
+      identifierType: 'registration_number',
+      regulator: 'KMPDC',
+      locationUuid: 'location-uuid-1',
+    });
+
+    expect(mockOpenmrsFetch).toHaveBeenCalledWith(
+      `${BASE_URL}/emt/handover/initiate`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          incidenceNumber: 'AMB-d22419d8-FAC',
+          identifier: 'A13579',
+          identifierType: 'registration_number',
+          regulator: 'KMPDC',
+          locationUuid: 'location-uuid-1',
+        },
+      },
+    );
+    expect(res.request_id).toBe('82fd22b6-e366-4077-9866-e1c4ed7328b0');
+  });
+
+  it('wraps a 409 conflict as EmtApiError(409)', async () => {
+    mockOpenmrsFetch.mockRejectedValueOnce(fetchError(409, 'Handover already initiated'));
+
+    try {
+      await initiateHandover({
+        incidenceNumber: 'AMB-d22419d8-FAC',
+        identifier: 'A13579',
+        identifierType: 'registration_number',
+        regulator: 'KMPDC',
+        locationUuid: 'location-uuid-1',
+      });
+      fail('Should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(EmtApiError);
+      expect((err as EmtApiError).status).toBe(409);
+    }
+  });
+});
+
+// ── verifyHandoverOtp ──────────────────────────────────────────────────
+
+describe('verifyHandoverOtp', () => {
+  it('POSTs to /handover/verify with incidenceNumber, request_id, and otp', async () => {
+    mockOpenmrsFetch.mockResolvedValueOnce({ data: { status: 'verified' } } as any);
+
+    await verifyHandoverOtp({
+      incidenceNumber: 'AMB-d22419d8-FAC',
+      requestId: '82fd22b6-e366-4077-9866-e1c4ed7328b0',
+      otp: '623415',
+      locationUuid: 'location-uuid-1',
+    });
+
+    expect(mockOpenmrsFetch).toHaveBeenCalledWith(
+      `${BASE_URL}/emt/handover/verify`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          incidenceNumber: 'AMB-d22419d8-FAC',
+          request_id: '82fd22b6-e366-4077-9866-e1c4ed7328b0',
+          otp: '623415',
+          locationUuid: 'location-uuid-1',
+        },
+      },
+    );
+  });
+
+  it('wraps an expired/invalid OTP (410) as EmtApiError(410)', async () => {
+    mockOpenmrsFetch.mockRejectedValueOnce(fetchError(410, 'OTP expired'));
+
+    try {
+      await verifyHandoverOtp({
+        incidenceNumber: 'AMB-d22419d8-FAC',
+        requestId: '82fd22b6-e366-4077-9866-e1c4ed7328b0',
+        otp: '000000',
+        locationUuid: 'location-uuid-1',
+      });
+      fail('Should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(EmtApiError);
+      expect((err as EmtApiError).status).toBe(410);
+    }
+  });
+});
+
+// ── normalizeError ────────────────────────────────────────────────────
+
+describe('normalizeError', () => {
+  it('reads the real HTTP status off an openmrsFetch-style error', () => {
+    const err = normalizeError(fetchError(404, 'Case not found'));
+    expect(err).toBeInstanceOf(EmtApiError);
+    expect(err.status).toBe(404);
+    expect(err.message).toBe('Case not found');
+  });
+
+  it('prefers a JSON responseBody.message when present', () => {
+    const err = normalizeError({
+      response: { status: 422 },
+      message: 'Server responded with 422',
+      responseBody: { message: 'identifier is required' },
+    });
+    expect(err.status).toBe(422);
+    expect(err.message).toBe('identifier is required');
+  });
+
+  it('returns status 0 for network / non-HTTP errors', () => {
+    const err = normalizeError(new Error('NetworkError: Failed to fetch'));
+    expect(err).toBeInstanceOf(EmtApiError);
+    expect(err.status).toBe(0);
+  });
+
+  it('passes an already-typed EmtApiError through unchanged', () => {
+    const original = new EmtApiError(409, 'Already handled');
+    expect(normalizeError(original)).toBe(original);
+  });
+});
+
+// ── getHandoverRequestId ──────────────────────────────────────────────
+
+describe('getHandoverRequestId', () => {
+  it('returns request_id (snake_case)', () => {
+    expect(getHandoverRequestId({ request_id: 'abc' })).toBe('abc');
+  });
+
+  it('falls back to requestId (camelCase)', () => {
+    expect(getHandoverRequestId({ requestId: 'def' })).toBe('def');
+  });
+
+  it('returns empty string when neither is present', () => {
+    expect(getHandoverRequestId({})).toBe('');
+  });
+});

package/src/emt/emt.resource.ts

@@ -0,0 +1,150 @@
+import useSWR from 'swr';
+import { openmrsFetch } from '@openmrs/esm-framework';
+import { getHieBaseUrl } from '../shared/utils/get-base-url';
+import {
+  EmtApiError,
+  type EmtReferral,
+  type EmtReferralListResponse,
+  type InitiateHandoverRequest,
+  type InitiateHandoverResponse,
+  type VerifyHandoverRequest,
+} from './types/emt.types';
+
+/**
+ * EMT / Referral data source.
+ *
+ * Endpoints are relative to the configured HIE base URL — `getHieBaseUrl()`,
+ * the same helper `registry.resource.ts`'s CR search and `preauth.resource.ts`'s
+ * HWR search already use — and go through `openmrsFetch`, so auth rides the
+ * real, current OpenMRS session instead of a hand-copied, expiring token.
+ */
+
+const EMT_BASE = '/emt';
+
+/** SWR cache key prefix for the pending-referrals list (used for invalidation). */
+export const EMT_PENDING_KEY = 'emt-pending-referrals';
+
+/** Default auto-refresh interval for the queue. SWR is the polling mechanism. */
+export const EMT_POLL_INTERVAL_MS = 30_000;
+
+/**
+ * Fetch a page of pending EMT referrals.
+ *
+ * The endpoint is server-paginated (`limit`/`offset`/`count`) — callers should
+ * page against the returned `count`, not assume a single page.
+ */
+export async function fetchPendingReferrals(
+  limit = 50,
+  offset = 0,
+  locationUuid = '',
+): Promise<EmtReferralListResponse> {
+  try {
+    const hieBaseUrl = await getHieBaseUrl();
+    const response = await openmrsFetch<EmtReferralListResponse>(
+      `${hieBaseUrl}${EMT_BASE}/referrals?limit=${limit}&offset=${offset}&locationUuid=${encodeURIComponent(locationUuid)}`,
+      { method: 'GET' },
+    );
+    const data = response?.data;
+    // Defensively normalise — never let a malformed envelope crash the queue.
+    return {
+      results: Array.isArray(data?.results) ? data.results : [],
+      count: typeof data?.count === 'number' ? data.count : data?.results?.length ?? 0,
+      limit: typeof data?.limit === 'number' ? data.limit : limit,
+      offset: typeof data?.offset === 'number' ? data.offset : offset,
+    };
+  } catch (err) {
+    throw normalizeError(err);
+  }
+}
+
+/**
+ * SWR hook for the pending-referrals queue.
+ *
+ * Polls on `EMT_POLL_INTERVAL_MS` (the repo has no global queue-polling
+ * convention — SWR focus/reconnect revalidation is the default; here we add an
+ * explicit refresh interval since EMT referrals arrive in real time).
+ */
+export function usePendingReferrals(limit = 50, offset = 0, locationUuid = '') {
+  const key = `${EMT_PENDING_KEY}:${limit}:${offset}:${locationUuid}`;
+  const { data, error, isLoading, isValidating, mutate } = useSWR(
+    key,
+    () => fetchPendingReferrals(limit, offset, locationUuid),
+    {
+      refreshInterval: EMT_POLL_INTERVAL_MS,
+      keepPreviousData: true,
+    },
+  );
+
+  return {
+    referrals: data?.results ?? [],
+    count: data?.count ?? 0,
+    limit: data?.limit ?? limit,
+    offset: data?.offset ?? offset,
+    isLoading,
+    isValidating,
+    error,
+    mutate,
+  };
+}
+
+/**
+ * Initiate a handover for a referral. The OTP is sent to the receiving doctor.
+ * Returns the `request_id` needed to call `verifyHandoverOtp`.
+ */
+export async function initiateHandover(
+  payload: InitiateHandoverRequest,
+): Promise<InitiateHandoverResponse> {
+  try {
+    const hieBaseUrl = await getHieBaseUrl();
+    const response = await openmrsFetch<InitiateHandoverResponse>(
+      `${hieBaseUrl}${EMT_BASE}/handover/initiate`,
+      { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: payload },
+    );
+    return response?.data;
+  } catch (err) {
+    throw normalizeError(err);
+  }
+}
+
+/** Extract the handover request id regardless of the response's casing. */
+export function getHandoverRequestId(res: InitiateHandoverResponse): string {
+  return res?.request_id ?? res?.requestId ?? '';
+}
+
+/**
+ * Verify the OTP entered by the receiving doctor and complete the handover.
+ * On success the referral is no longer `pending_acceptance` and the patient's
+ * visit should be started.
+ */
+export async function verifyHandoverOtp(payload: VerifyHandoverRequest) {
+  try {
+    const hieBaseUrl = await getHieBaseUrl();
+    const response = await openmrsFetch(`${hieBaseUrl}${EMT_BASE}/handover/verify`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: payload,
+    });
+    return response?.data;
+  } catch (err) {
+    throw normalizeError(err);
+  }
+}
+
+/**
+ * Map an upstream failure into a typed `EmtApiError` carrying the HTTP status,
+ * so the UI can branch on the distinct cases (auth, already-handled, conflict,
+ * validation, OTP, …). `openmrsFetch` throws `OpenmrsFetchError`, which carries
+ * the real `response.status` — no message-parsing needed. Anything without a
+ * status (a raw network failure) is treated as status 0.
+ */
+export function normalizeError(err: any): EmtApiError {
+  if (err instanceof EmtApiError) {
+    return err;
+  }
+  const status = typeof err?.response?.status === 'number' ? err.response.status : 0;
+  const message: string =
+    (typeof err?.responseBody === 'object' && err?.responseBody?.message) ||
+    (typeof err?.message === 'string' && err.message) ||
+    'Unexpected error from the EMT service.';
+  return new EmtApiError(status, message);
+}

package/src/emt/handover-modal/handover-modal.component.test.tsx

@@ -0,0 +1,273 @@
+/**
+ * Tests for the OTP-verified handover flow: resolving the receiving doctor
+ * (provider + HWR search), initiate success/failure, verify success/failure,
+ * and the "already handled elsewhere" (404) race condition on both calls.
+ */
+import React from 'react';
+import { act, render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+const mockShowSnackbar = jest.fn();
+jest.mock('@openmrs/esm-framework', () => ({
+  showSnackbar: (...args: unknown[]) => mockShowSnackbar(...args),
+}));
+
+const mockInitiateHandover = jest.fn();
+const mockVerifyHandoverOtp = jest.fn();
+jest.mock('../emt.resource', () => ({
+  initiateHandover: (...args: unknown[]) => mockInitiateHandover(...args),
+  verifyHandoverOtp: (...args: unknown[]) => mockVerifyHandoverOtp(...args),
+  getHandoverRequestId: (res: any) => res?.request_id ?? res?.requestId ?? '',
+}));
+
+const mockSearchOpenMrsProviders = jest.fn();
+const mockSearchHealthWorkerRegistry = jest.fn();
+jest.mock('../../billing/dashboard/v3/preauth/preauth.resource', () => ({
+  searchOpenMrsProviders: (...args: unknown[]) => mockSearchOpenMrsProviders(...args),
+  searchHealthWorkerRegistry: (...args: unknown[]) => mockSearchHealthWorkerRegistry(...args),
+}));
+
+import { EmtApiError, type EmtReferralRow } from '../types/emt.types';
+import HandoverModal from './handover-modal.component';
+
+const referral: EmtReferralRow = {
+  submission_id: 3,
+  cr_id: 'CR5617849204955-8',
+  status: 'pending_acceptance',
+  incident_id: 'INC-20260803100645-254727092999-ffjotq',
+  dispatch_id: 'd22419d8-6d36-4b2f-a33c-3e008bd85f77',
+  case_number: 'AMB-d22419d8-FAC',
+  ambulance_fr_code: 'FID-AMB-916293-3',
+  ambulance_registration_number: 'KDN 085T',
+  facility_fr_code: 'FID-47-108521-3',
+  evacuation_scene: '',
+  priority: 'p1 life threatening (als) with altered consciousness',
+  referral_reason: '',
+  referral_category: '',
+  transport_modality: '',
+  referral_notes: 'Chief complaint: Test.',
+  bundle_id: 'd22419d8-6d36-4b2f-a33c-3e008bd85f77',
+  interventions: ['SHA-01-001'],
+  requested_at: '2026-08-04T09:37:39.438967Z',
+  updated_at: '2026-08-04T09:37:40.428903Z',
+  patientName: 'Jane Doe',
+  crLoading: false,
+};
+
+const providerHit = {
+  uuid: 'provider-uuid-1',
+  display: 'Dr. Alice Mwangi',
+  identifier: 'PROV-1',
+  nationalId: '12345678',
+};
+
+const hwrHitFixture = {
+  membership: {
+    full_name: 'Dr. Alice Mwangi',
+    registration_id: 'A13579',
+    licensing_body: 'Kenya Medical Practitioners and Dentists Council',
+  },
+};
+
+function baseProps() {
+  return {
+    referral,
+    locationUuid: 'location-uuid-1',
+    closeWorkspace: jest.fn(),
+    promptBeforeClosing: jest.fn(),
+    onHandoverComplete: jest.fn(),
+    onReferralUnavailable: jest.fn(),
+  };
+}
+
+/** Drives the modal from the initial "doctor" step through to "confirm". */
+async function resolveDoctorAndContinue(user: ReturnType<typeof userEvent.setup>) {
+  mockSearchOpenMrsProviders.mockResolvedValueOnce([providerHit]);
+  mockSearchHealthWorkerRegistry.mockResolvedValueOnce([hwrHitFixture]);
+
+  await user.type(screen.getByPlaceholderText(/type at least 2 characters/i), 'Alice');
+  const option = await screen.findByText(/Dr\. Alice Mwangi/, {}, { timeout: 2000 });
+  await user.click(option);
+
+  await screen.findByText(/A13579/);
+  await waitFor(() => expect(screen.getByRole('button', { name: /continue/i })).toBeEnabled());
+  await user.click(screen.getByRole('button', { name: /continue/i }));
+
+  await screen.findByText(/confirm handover/i);
+}
+
+function typeOtp(container: HTMLElement, digits: string) {
+  const inputs = Array.from(container.querySelectorAll('input[id^="otp-"]')) as HTMLInputElement[];
+  act(() => {
+    digits.split('').forEach((digit, i) => {
+      fireEventChange(inputs[i], digit);
+    });
+  });
+}
+
+// OTPInput expects a native change event; userEvent.type works too but this is
+// faster and avoids per-keystroke debounce concerns in this digit widget.
+function fireEventChange(input: HTMLInputElement, value: string) {
+  const nativeInputValueSetter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value')!.set!;
+  nativeInputValueSetter.call(input, value);
+  input.dispatchEvent(new Event('input', { bubbles: true }));
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+describe('doctor resolution', () => {
+  it('resolves the receiving doctor via provider + HWR search and gates Continue on it', async () => {
+    const user = userEvent.setup();
+    render(<HandoverModal {...baseProps()} />);
+
+    expect(screen.getByRole('button', { name: /continue/i })).toBeDisabled();
+    await resolveDoctorAndContinue(user);
+
+    expect(mockSearchHealthWorkerRegistry).toHaveBeenCalledWith({
+      identifierType: 'National ID',
+      identifierValue: '12345678',
+      locationUuid: 'location-uuid-1',
+    });
+    expect(screen.getByText(/KMPDC/)).toBeInTheDocument();
+    expect(screen.getByText(/A13579/)).toBeInTheDocument();
+  });
+
+  it('lets staff proceed to a manual National ID search when the provider has none on file', async () => {
+    mockSearchOpenMrsProviders.mockResolvedValueOnce([{ uuid: 'p2', display: 'Dr. No Id' }]);
+    const user = userEvent.setup();
+    render(<HandoverModal {...baseProps()} />);
+
+    await user.type(screen.getByPlaceholderText(/type at least 2 characters/i), 'No Id');
+    await user.click(await screen.findByText('Dr. No Id'));
+
+    expect(await screen.findByText(/enter it manually and search hwr/i)).toBeInTheDocument();
+    expect(mockSearchHealthWorkerRegistry).not.toHaveBeenCalled();
+
+    mockSearchHealthWorkerRegistry.mockResolvedValueOnce([hwrHitFixture]);
+    await user.type(screen.getByLabelText(/doctor national id/i), '99999999');
+    await user.click(screen.getByRole('button', { name: /search hwr/i }));
+
+    await screen.findByText(/A13579/);
+    expect(screen.getByRole('button', { name: /continue/i })).toBeEnabled();
+  });
+
+  it('keeps Continue disabled when the HWR hit has no registration number', async () => {
+    mockSearchOpenMrsProviders.mockResolvedValueOnce([providerHit]);
+    mockSearchHealthWorkerRegistry.mockResolvedValueOnce([{ membership: { full_name: 'Dr. No Reg' } }]);
+    const user = userEvent.setup();
+    render(<HandoverModal {...baseProps()} />);
+
+    await user.type(screen.getByPlaceholderText(/type at least 2 characters/i), 'Alice');
+    await user.click(await screen.findByText(/Dr\. Alice Mwangi/));
+
+    expect(await screen.findByText(/no registration number on file/i)).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /continue/i })).toBeDisabled();
+  });
+});
+
+describe('initiate', () => {
+  it('on success: sends the exact request body and moves to the OTP step', async () => {
+    mockInitiateHandover.mockResolvedValueOnce({ request_id: 'req-123' });
+    const user = userEvent.setup();
+    render(<HandoverModal {...baseProps()} />);
+    await resolveDoctorAndContinue(user);
+
+    await user.click(screen.getByRole('button', { name: /send otp/i }));
+
+    expect(mockInitiateHandover).toHaveBeenCalledWith({
+      incidenceNumber: 'AMB-d22419d8-FAC',
+      identifier: 'A13579',
+      identifierType: 'registration_number',
+      regulator: 'KMPDC',
+      locationUuid: 'location-uuid-1',
+    });
+    expect(await screen.findByText(/enter doctor otp/i)).toBeInTheDocument();
+  });
+
+  it('on a 409 conflict: shows a distinct inline message and stays on confirm', async () => {
+    mockInitiateHandover.mockRejectedValueOnce(new EmtApiError(409, 'Request failed with 409'));
+    const user = userEvent.setup();
+    render(<HandoverModal {...baseProps()} />);
+    await resolveDoctorAndContinue(user);
+
+    await user.click(screen.getByRole('button', { name: /send otp/i }));
+
+    expect(await screen.findByText(/already been initiated or completed/i)).toBeInTheDocument();
+    expect(screen.getByText(/confirm handover/i)).toBeInTheDocument();
+  });
+
+  it('on 404 (already handled elsewhere): notifies the parent instead of showing an inline error', async () => {
+    mockInitiateHandover.mockRejectedValueOnce(new EmtApiError(404, 'Request failed with 404'));
+    const props = baseProps();
+    const user = userEvent.setup();
+    render(<HandoverModal {...props} />);
+    await resolveDoctorAndContinue(user);
+
+    await user.click(screen.getByRole('button', { name: /send otp/i }));
+
+    await waitFor(() => expect(props.onReferralUnavailable).toHaveBeenCalledWith(referral, expect.stringMatching(/handled elsewhere/i)));
+    expect(screen.queryByText(/already been initiated or completed/i)).not.toBeInTheDocument();
+  });
+});
+
+describe('verify', () => {
+  async function getToOtpStep(user: ReturnType<typeof userEvent.setup>) {
+    mockInitiateHandover.mockResolvedValueOnce({ request_id: 'req-123' });
+    await resolveDoctorAndContinue(user);
+    await user.click(screen.getByRole('button', { name: /send otp/i }));
+    await screen.findByText(/enter doctor otp/i);
+  }
+
+  it('on success: verifies with incidenceNumber/requestId/otp and completes the handover', async () => {
+    const user = userEvent.setup();
+    const props = baseProps();
+    const { container } = render(<HandoverModal {...props} />);
+    await getToOtpStep(user);
+
+    typeOtp(container, '654321');
+    await waitFor(() => expect(screen.getByRole('button', { name: /verify/i })).toBeEnabled());
+    mockVerifyHandoverOtp.mockResolvedValueOnce({ status: 'verified' });
+    await user.click(screen.getByRole('button', { name: /verify/i }));
+
+    await waitFor(() =>
+      expect(mockVerifyHandoverOtp).toHaveBeenCalledWith({
+        incidenceNumber: 'AMB-d22419d8-FAC',
+        requestId: 'req-123',
+        otp: '654321',
+        locationUuid: 'location-uuid-1',
+      }),
+    );
+    expect(props.onHandoverComplete).toHaveBeenCalledWith(referral);
+  });
+
+  it('on an invalid/expired OTP: keeps the modal open on the OTP step with a specific message', async () => {
+    const user = userEvent.setup();
+    const props = baseProps();
+    const { container } = render(<HandoverModal {...props} />);
+    await getToOtpStep(user);
+
+    typeOtp(container, '000000');
+    mockVerifyHandoverOtp.mockRejectedValueOnce(new EmtApiError(410, 'Request failed with 410'));
+    await user.click(screen.getByRole('button', { name: /verify/i }));
+
+    expect(await screen.findByText(/otp has expired/i)).toBeInTheDocument();
+    expect(screen.getByText(/enter doctor otp/i)).toBeInTheDocument();
+    expect(props.onHandoverComplete).not.toHaveBeenCalled();
+  });
+
+  it('on 404 (already handled elsewhere) during verify: notifies the parent, does not complete the handover', async () => {
+    const user = userEvent.setup();
+    const props = baseProps();
+    const { container } = render(<HandoverModal {...props} />);
+    await getToOtpStep(user);
+
+    typeOtp(container, '654321');
+    mockVerifyHandoverOtp.mockRejectedValueOnce(new EmtApiError(404, 'Request failed with 404'));
+    await user.click(screen.getByRole('button', { name: /verify/i }));
+
+    await waitFor(() => expect(props.onReferralUnavailable).toHaveBeenCalledWith(referral, expect.stringMatching(/handled elsewhere/i)));
+    expect(props.onHandoverComplete).not.toHaveBeenCalled();
+  });
+});