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

package/src/shr/shr.resource.ts

@@ -0,0 +1,463 @@
+import dayjs from 'dayjs';
+import { openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import { getHieBaseUrl } from '../shared/utils/get-base-url';
+import { IdentifierTypesUuids } from '../resources/identifier-types';
+import {
+  ShrApiError,
+  type ActiveConsentResponse,
+  type CloseVisitRequest,
+  type CloseVisitResponse,
+  type CreateConsentRequest,
+  type CreateConsentResponse,
+  type OpenVisitsResponse,
+  type RefreshConsentResponse,
+  type ShrAnyResource,
+  type ShrRecordSet,
+  type ShrVisitSubmissionRequest,
+  type ShrVisitSubmissionResponse,
+  type VerifyConsentRequest,
+  type VerifyConsentResponse,
+} from './shr.types';
+
+/**
+ * Shared Health Record (SHR) data source.
+ *
+ * All endpoints are relative to the configured HIE base URL —
+ * `getHieBaseUrl()`, the same helper the CR search, EMT and claims calls use —
+ * and go through `openmrsFetch`, so session auth rides the live OpenMRS cookie.
+ * The raw curl examples set a `Cookie` header by hand; we deliberately don't.
+ */
+
+const SHR_BASE = '/shr';
+
+/** Envelope keys an SHR payload might hide a resource list under. */
+const RESOURCE_LIST_KEYS = ['entry', 'entries', 'resources', 'records', 'results', 'data', 'bundle', 'bundles'];
+
+/**
+ * Create a consent request.
+ *
+ * Normally the backend dispatches an OTP and returns the `consent_id` +
+ * `otp_record` pair the verify call needs. An **emergency** request is approved
+ * on the spot instead and comes back with `consent_token` + `visit_id` and no
+ * `otp_record` — callers must branch on the response, not on what they asked
+ * for.
+ */
+export async function createConsentRequest(payload: CreateConsentRequest): Promise<CreateConsentResponse> {
+  try {
+    const hieBaseUrl = await getHieBaseUrl();
+    const response = await openmrsFetch<CreateConsentResponse>(`${hieBaseUrl}${SHR_BASE}/consents`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: payload,
+    });
+    return response?.data;
+  } catch (err) {
+    throw normalizeError(err);
+  }
+}
+
+/**
+ * Record a consent decision. One endpoint, three outcomes — an approval
+ * (`consent_token` + `visit_id`), a refusal (`consent_status`, no token), or the
+ * completion of an OTP-gated closure (`end_date`) — so callers branch on which
+ * fields actually came back. `visit_id` has no other source than an approval.
+ */
+export async function verifyConsentOtp(
+  consentId: string,
+  payload: VerifyConsentRequest,
+): Promise<VerifyConsentResponse> {
+  try {
+    const hieBaseUrl = await getHieBaseUrl();
+    const response = await openmrsFetch<VerifyConsentResponse>(
+      `${hieBaseUrl}${SHR_BASE}/consents/${encodeURIComponent(consentId)}/verify`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: payload,
+      },
+    );
+    return response?.data;
+  } catch (err) {
+    throw normalizeError(err);
+  }
+}
+
+/**
+ * Fetch the patient's shared records for the requested resource types.
+ *
+ * `resources` is built by joining the configured resource types, so adding or
+ * removing a viewer category is a config change (see `shrResourceTypes`) rather
+ * than a code change. The consent token is passed as `X-Consent-Token`.
+ */
+export async function fetchPatientRecords({
+  crId,
+  resourceTypes,
+  locationUuid,
+  consentToken,
+}: {
+  crId: string;
+  resourceTypes: string[];
+  locationUuid: string;
+  consentToken: string;
+}): Promise<ShrRecordSet> {
+  try {
+    const hieBaseUrl = await getHieBaseUrl();
+    const params = new URLSearchParams({
+      crId,
+      resources: resourceTypes.join(','),
+      locationUuid,
+    });
+    const response = await openmrsFetch<unknown>(`${hieBaseUrl}${SHR_BASE}/patient-records?${params.toString()}`, {
+      method: 'GET',
+      headers: { 'X-Consent-Token': consentToken },
+    });
+    return summariseRecords(response?.data);
+  } catch (err) {
+    throw normalizeError(err);
+  }
+}
+
+/**
+ * Close the SHR visit opened by a granted consent. `visitId` is the `visit_id`
+ * captured from the verify response.
+ *
+ * "Consent closure initiated." with `status: "success"` does **not** mean the
+ * visit is closed: the default path is OTP-gated, so the response carries an
+ * `otp_record` and the visit stays open until that password is verified. Only
+ * `end_date` means closed. Callers must branch on which arrived.
+ *
+ * Pass `patientIncapable: 1` (with `incapacityReason`) for a patient who cannot
+ * consent to their own closure — unconscious or deceased — which closes the
+ * visit immediately with no OTP. See `CloseVisitRequest` for the polarity trap
+ * against the consent request's `patientCapable`.
+ */
+export async function closeShrVisit(
+  visitId: string,
+  locationUuid: string,
+  options: Omit<CloseVisitRequest, 'locationUuid'> = {},
+): Promise<CloseVisitResponse> {
+  try {
+    const hieBaseUrl = await getHieBaseUrl();
+    const body: CloseVisitRequest = {
+      locationUuid,
+      ...(options.patientIncapable !== undefined ? { patientIncapable: options.patientIncapable } : {}),
+      ...(options.incapacityReason ? { incapacityReason: options.incapacityReason } : {}),
+    };
+    const response = await openmrsFetch<CloseVisitResponse>(
+      `${hieBaseUrl}${SHR_BASE}/visits/${encodeURIComponent(visitId)}/close`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+      },
+    );
+    return response?.data;
+  } catch (err) {
+    throw normalizeError(err);
+  }
+}
+
+/**
+ * Submit the patient's latest closed visit to the SHA as a FHIR collection
+ * bundle — the visit-closed counterpart to `closeShrVisit`: once the OpenMRS
+ * visit has been closed, this pushes its clinical content (encounters, vitals,
+ * diagnoses) into the national Shared Health Record.
+ *
+ * The whole job happens backend-side (hie-saf, `src/shr/visit-submission` —
+ * browsers cannot reach the SHA host through the O3 CSP): given a
+ * `patientUuid` + `locationUuid`, the backend picks the latest closed visit
+ * on the caller's session, maps it to the SHA-IG-conformant bundle shape —
+ * the emergency family (the enforced em-* profiles) or, for routine care,
+ * the clinical family (a base-R4 Encounter; pick via `submissionFamily`,
+ * otherwise the visit type decides) — optionally pre-validates with
+ * `$validate`, and submits through DHA's middleware (`POST /shr/bundles`,
+ * consent-token enforced). This function is just the typed call.
+ *
+ * `skipped` (no closed visit) and `validated` (a `dryRun`) come back on HTTP
+ * 200 alongside `submitted`; only `status: "failed"` is an error state, and it
+ * arrives as a thrown `ShrApiError` carrying the backend's `errors`.
+ */
+export async function submitClosedVisitToShr(payload: ShrVisitSubmissionRequest): Promise<ShrVisitSubmissionResponse> {
+  try {
+    const hieBaseUrl = await getHieBaseUrl();
+    const response = await openmrsFetch<ShrVisitSubmissionResponse>(`${hieBaseUrl}${SHR_BASE}/visit-submission`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: payload,
+    });
+    return response?.data;
+  } catch (err) {
+    throw normalizeError(err);
+  }
+}
+
+/**
+ * The visits at this facility that still hold an open consent for the patient.
+ *
+ * Worth calling before starting a new consent request: an open visit can be
+ * reused via `refreshVisitConsent` instead of putting the patient through
+ * another OTP, and a patient with one open here cannot start a second.
+ */
+export async function listOpenVisits(crId: string, locationUuid: string): Promise<OpenVisitsResponse> {
+  try {
+    const hieBaseUrl = await getHieBaseUrl();
+    const params = new URLSearchParams({ crId, locationUuid });
+    const response = await openmrsFetch<OpenVisitsResponse>(
+      `${hieBaseUrl}${SHR_BASE}/open-visits?${params.toString()}`,
+      { method: 'GET' },
+    );
+    return response?.data ?? { visits: [] };
+  } catch (err) {
+    throw normalizeError(err);
+  }
+}
+
+/**
+ * A fresh consent token for an open visit, for when the token issued at
+ * verification has expired but the visit is still open.
+ */
+export async function refreshVisitConsent(
+  visitId: string,
+  locationUuid: string,
+  consentToken?: string,
+): Promise<RefreshConsentResponse> {
+  try {
+    const hieBaseUrl = await getHieBaseUrl();
+    const response = await openmrsFetch<RefreshConsentResponse>(
+      `${hieBaseUrl}${SHR_BASE}/visits/${encodeURIComponent(visitId)}/refresh`,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...(consentToken ? { 'X-Consent-Token': consentToken } : {}),
+        },
+        body: { locationUuid },
+      },
+    );
+    return response?.data;
+  } catch (err) {
+    throw normalizeError(err);
+  }
+}
+
+/**
+ * "Do we already have a usable consent for this patient here?" — the backend's
+ * own convenience route, which checks its recorded session, falls back to DHA's
+ * open visits, and refreshes whichever it finds.
+ *
+ * Preferred over any local-only cache because it sees visits opened from
+ * another device or browser. `hasActiveConsent: false` is a normal answer.
+ */
+export async function getActiveConsent(crId: string, locationUuid: string): Promise<ActiveConsentResponse> {
+  try {
+    const hieBaseUrl = await getHieBaseUrl();
+    const params = new URLSearchParams({ crId, locationUuid });
+    const response = await openmrsFetch<ActiveConsentResponse>(
+      `${hieBaseUrl}${SHR_BASE}/consents/active?${params.toString()}`,
+      { method: 'GET' },
+    );
+    return response?.data ?? { hasActiveConsent: false };
+  } catch (err) {
+    throw normalizeError(err);
+  }
+}
+
+/**
+ * The patient's Client Registry (CR) number, read off their OpenMRS identifiers.
+ *
+ * Ported from `ampath-esm-hie-registry-manager-app`'s
+ * `getPatientCrIdentifier` — this is how `crId` is derived for the consent
+ * request, so the clinician never types it. The identifier type defaults to the
+ * CR number type this repo already pins in two places
+ * (`IdentifierTypesUuids.CLIENT_REGISTRY_NO_UUID` and the
+ * `electivePreauth.clientRegistryIdentifierTypeUuid` config), and callers with
+ * config in hand should pass the configured value.
+ *
+ * Returns an empty string when the patient has no CR number — the caller must
+ * treat that as "cannot request SHR consent" rather than sending an empty crId.
+ */
+export async function getPatientCrIdentifier(
+  patientUuid: string,
+  identifierTypeUuid: string = IdentifierTypesUuids.CLIENT_REGISTRY_NO_UUID,
+): Promise<string> {
+  if (!patientUuid) {
+    return '';
+  }
+  try {
+    const response = await openmrsFetch<{
+      results?: Array<{ identifier?: string; identifierType?: { uuid?: string } }>;
+    }>(`${restBaseUrl}/patient/${patientUuid}/identifier`, { method: 'GET' });
+    const identifiers = response?.data?.results ?? [];
+    const match = identifiers.find((id) => id?.identifierType?.uuid === identifierTypeUuid);
+    return match?.identifier ?? '';
+  } catch (err) {
+    throw normalizeError(err);
+  }
+}
+
+/**
+ * Whether the patient is under 18, which decides whether the consent request
+ * needs a representative (see `CreateConsentRequest`'s decision table).
+ *
+ * Mirrors the `isMinor` checks already in this repo — `send-to-queue.modal.tsx`
+ * and `submit-claim.modal.tsx` — which compute the same thing off two different
+ * patient shapes. The SHR tab reads a FHIR-shaped `usePatient()`, so `birthDate`
+ * is the field on hand, but the OpenMRS REST shape (`person.age` /
+ * `person.birthdate`) is accepted too so this survives being handed either.
+ *
+ * A missing or unparseable birth date is treated as **not** a minor: the adult
+ * flow puts the "patient unable to consent" decision in the clinician's hands,
+ * whereas wrongly forcing the minor flow would demand a representative for an
+ * adult who can consent perfectly well.
+ */
+export function isMinorPatient(patient: unknown): boolean {
+  const record = (patient ?? {}) as Record<string, any>;
+  const person = (record.person ?? {}) as Record<string, any>;
+
+  const age = person.age ?? record.age;
+  if (typeof age === 'number' && Number.isFinite(age)) {
+    return age < 18;
+  }
+
+  const birthDate = record.birthDate ?? person.birthdate ?? person.birthDate;
+  if (!birthDate) {
+    return false;
+  }
+  // `isValid()` rather than a finiteness check on the difference: dayjs's
+  // year-diff against an invalid date returns 0, not NaN, so an unparseable
+  // birth date would otherwise read as a newborn — a minor — which is the exact
+  // wrong direction to fail in.
+  const parsed = dayjs(birthDate as string);
+  if (!parsed.isValid()) {
+    return false;
+  }
+  const computedAge = dayjs().diff(parsed, 'year');
+  return Number.isFinite(computedAge) && computedAge < 18;
+}
+
+/**
+ * Map an upstream failure into a typed `ShrApiError` carrying the HTTP status.
+ * `openmrsFetch` throws `OpenmrsFetchError`, which already carries the real
+ * `response.status`; a raw network failure has none and becomes status 0.
+ *
+ * The raw upstream message is kept intact here — the nested-JSON unwrapping in
+ * `extractShrErrorDetail` happens only at the point of display.
+ */
+export function normalizeError(err: any): ShrApiError {
+  if (err instanceof ShrApiError) {
+    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?.responseBody === 'string' && err.responseBody) ||
+    (typeof err?.message === 'string' && err.message) ||
+    'Unexpected error from the SHR service.';
+  return new ShrApiError(status, message);
+}
+
+/**
+ * Unwrap the doubly-encoded upstream error the verify endpoint returns, e.g.
+ *
+ *   "failed to verify patient consent: {\"status\": \"error\", … \"message\": \"OTP already used.\"}"
+ *
+ * Never assume it parses: anything unexpected falls back to a generic line.
+ * Applied to all four endpoints, since we only have evidence for verify and no
+ * reason to assume the others never nest their errors the same way.
+ */
+export function extractShrErrorDetail(rawMessage: string): string {
+  const fallback = 'We could not verify that code. Try again or resend the OTP.';
+  try {
+    const idx = rawMessage?.indexOf('{') ?? -1;
+    if (idx === -1) {
+      return rawMessage || fallback;
+    }
+    const inner = JSON.parse(rawMessage.slice(idx));
+    return inner?.message || fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Flatten whatever envelope the patient-records response arrives in into a flat
+ * list of FHIR resources.
+ *
+ * The endpoint is new and its exact envelope is unconfirmed, so rather than
+ * hardcoding `Bundle.entry[].resource` this walks the plausible shapes — a FHIR
+ * bundle, a bundle of per-type searchset bundles, a bare array, a
+ * resourceType-keyed map, or a `{ resources: [...] }`-style wrapper — and
+ * collects anything that looks like a resource. Bundles and OperationOutcomes
+ * are traversed, not counted.
+ */
+export function flattenShrResources(payload: unknown): ShrAnyResource[] {
+  const collected: ShrAnyResource[] = [];
+  const seen = new Set<unknown>();
+
+  const walk = (node: unknown, depth: number) => {
+    if (!node || depth > 8) {
+      return;
+    }
+    if (Array.isArray(node)) {
+      node.forEach((item) => walk(item, depth + 1));
+      return;
+    }
+    if (typeof node !== 'object') {
+      return;
+    }
+    if (seen.has(node)) {
+      return;
+    }
+    seen.add(node);
+
+    const obj = node as Record<string, any>;
+    const resourceType = typeof obj.resourceType === 'string' ? obj.resourceType : '';
+
+    if (resourceType && resourceType !== 'Bundle' && resourceType !== 'OperationOutcome') {
+      collected.push(obj as ShrAnyResource);
+      return;
+    }
+
+    // A bundle (or an unlabelled envelope): descend into whichever list it carries.
+    if (obj.resource) {
+      walk(obj.resource, depth + 1);
+    }
+    for (const key of RESOURCE_LIST_KEYS) {
+      if (obj[key]) {
+        walk(obj[key], depth + 1);
+      }
+    }
+    // Last resort: a map keyed by resource type, e.g. { Encounter: [...], Condition: [...] }.
+    if (!resourceType) {
+      for (const [key, value] of Object.entries(obj)) {
+        if (RESOURCE_LIST_KEYS.includes(key) || key === 'resource') {
+          continue;
+        }
+        if (Array.isArray(value) && /^[A-Z][A-Za-z]+$/.test(key)) {
+          walk(value, depth + 1);
+        }
+      }
+    }
+  };
+
+  walk(payload, 0);
+  return collected;
+}
+
+/** Flatten a records payload and pull out the few summary facts the viewer's tiles show. */
+export function summariseRecords(payload: unknown): ShrRecordSet {
+  const resources = flattenShrResources(payload);
+  const sources = Array.from(
+    new Set(resources.map((r) => r?.meta?.source?.trim()).filter((s): s is string => Boolean(s))),
+  );
+  const timestamps = resources
+    .map((r) => r?.meta?.lastUpdated)
+    .filter((v): v is string => Boolean(v))
+    .sort();
+  return {
+    resources,
+    lastUpdated: timestamps.length ? timestamps[timestamps.length - 1] : undefined,
+    sources,
+    raw: payload,
+  };
+}

package/src/shr/shr.scss

@@ -0,0 +1,114 @@
+@use '@carbon/colors';
+@use '@carbon/layout';
+@use '@carbon/type';
+
+.container {
+  min-width: 0;
+  background-color: colors.$gray-10;
+}
+
+.statusView {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  gap: layout.$spacing-03;
+  padding: layout.$spacing-09 layout.$spacing-05;
+  min-width: 0;
+}
+
+.statusTitle {
+  @include type.type-style('heading-compact-02');
+  color: colors.$gray-100;
+  margin: layout.$spacing-03 0 0;
+}
+
+.statusText {
+  @include type.type-style('body-compact-01');
+  color: colors.$gray-70;
+  margin: 0;
+  max-width: 26rem;
+}
+
+.statusNotice {
+  width: 100%;
+  max-width: 30rem;
+  text-align: left;
+}
+
+.statusActions {
+  display: flex;
+  gap: layout.$spacing-03;
+  margin-top: layout.$spacing-03;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+
+.iconAccent {
+  color: colors.$blue-60;
+}
+
+.iconMuted {
+  color: colors.$gray-70;
+}
+
+.iconDanger {
+  color: colors.$red-60;
+}
+
+.iconSuccess {
+  color: colors.$green-50;
+}
+
+.iconWarning {
+  color: colors.$orange-40;
+}
+
+// The closure confirmation that stands in front of "Close visit". Rendered
+// inside the viewer (under its header) and inside the empty state, so it sizes
+// to its container rather than assuming either one's width.
+.closePanel {
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-04;
+  padding: layout.$spacing-05;
+  background-color: colors.$white;
+  border: 1px solid colors.$gray-20;
+  border-left: 3px solid colors.$red-60;
+  text-align: left;
+  min-width: 0;
+}
+
+.closePanelTitle {
+  @include type.type-style('heading-compact-01');
+  margin: 0;
+}
+
+.closePanelText {
+  @include type.type-style('body-compact-01');
+  color: colors.$gray-70;
+  margin: 0;
+}
+
+.closePanelActions {
+  display: flex;
+  gap: layout.$spacing-03;
+  flex-wrap: wrap;
+}
+
+// The closure OTP sits in the centred status layout, so it stacks and centres
+// rather than inheriting the form-style left alignment.
+.closeOtp {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: layout.$spacing-04;
+}
+
+.otpField {
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-03;
+  align-items: center;
+}