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

package/src/shr/shr-code-systems.json

@@ -0,0 +1,363 @@
+{
+  "em-age-group": {
+    "adult": "Adult",
+    "paediatric": "Paediatric"
+  },
+  "em-agency-type": {
+    "ems": "Emergency medical services",
+    "fire": "Fire and rescue service",
+    "police": "Police service",
+    "security": "Security service",
+    "disaster-management": "Disaster management service",
+    "military": "Military service",
+    "community-response": "Community emergency response",
+    "other": "Other supporting agency"
+  },
+  "em-body-assessment-finding": {
+    "abrasion": "Abrasion",
+    "burn": "Burn",
+    "contusion": "Contusion",
+    "deformity": "Deformity",
+    "fracture": "Fracture",
+    "hemorrhage": "Hemorrhage",
+    "laceration": "Laceration",
+    "pain": "Pain",
+    "rigidity": "Rigidity",
+    "swelling": "Swelling",
+    "tenderness": "Tenderness",
+    "normal-finding": "Normal finding"
+  },
+  "em-body-region": {
+    "XA20Q1": "Head",
+    "XA7AA6": "Neck",
+    "XA55T2": "Chest",
+    "XA2P90": "Back and spine",
+    "XA6GV0": "Abdomen",
+    "XA8Y23": "Pelvis",
+    "XA4BA8": "Upper extremities",
+    "XA45A6": "Lower extremities"
+  },
+  "em-breathing-status": {
+    "normal": "Normal",
+    "labored": "Labored",
+    "gasping": "Gasping",
+    "absent": "Absent",
+    "unknown": "Unknown"
+  },
+  "em-caller-relationship": {
+    "self": "Self",
+    "parent": "Parent",
+    "spouse": "Spouse",
+    "sibling": "Sibling",
+    "relative": "Other relative",
+    "caregiver": "Caregiver",
+    "bystander": "Bystander",
+    "other": "Other",
+    "unknown": "Unknown"
+  },
+  "em-clinical-acuity": {
+    "red": "Red - Immediate",
+    "orange": "Orange - Very urgent",
+    "yellow": "Yellow - Urgent",
+    "green": "Green - Routine",
+    "blue": "Blue - Non-urgent",
+    "black": "Black - Deceased or expectant",
+    "unknown": "Unknown"
+  },
+  "em-crew-role": {
+    "crew-lead": "Crew lead",
+    "emergency-physician": "Emergency physician",
+    "paramedic": "Paramedic",
+    "emt": "Emergency medical technician",
+    "nurse": "Emergency nurse",
+    "driver": "Emergency vehicle driver",
+    "dispatcher": "Dispatcher",
+    "observer": "Observer",
+    "other": "Other crew role"
+  },
+  "em-destination-facility-type": {
+    "dispensary": "Dispensary",
+    "health-centre": "Health centre",
+    "hospital": "Hospital",
+    "emergency-centre": "Emergency centre",
+    "trauma-centre": "Trauma centre",
+    "maternity": "Maternity facility",
+    "mental-health-facility": "Mental health facility",
+    "specialist-facility": "Specialist facility",
+    "temporary-treatment-centre": "Temporary treatment centre",
+    "other": "Other destination facility"
+  },
+  "em-diagnosis-category": {
+    "chief-complaint": "Chief complaint",
+    "working-diagnosis": "Working diagnosis",
+    "differential-diagnosis": "Differential diagnosis",
+    "discharge-diagnosis": "Discharge diagnosis"
+  },
+  "em-dispatch-priority": {
+    "P1": "Priority 1 – Immediate",
+    "P2": "Priority 2 – Urgent",
+    "P3": "Priority 3 – Non-urgent",
+    "P4": "Priority 4 – Advice or scheduled response",
+    "unknown": "Unknown"
+  },
+  "em-emergency-centre-capability": {
+    "none": "No dedicated emergency centre",
+    "basic": "Basic emergency capability",
+    "intermediate": "Intermediate emergency capability",
+    "advanced": "Advanced emergency capability",
+    "trauma-centre": "Designated trauma centre",
+    "specialized": "Specialized emergency service",
+    "unknown": "Unknown emergency capability"
+  },
+  "em-encounter-class": {
+    "FLD": "Emergency medical services field response"
+  },
+  "em-facility-level": {
+    "level-1": "Level 1",
+    "level-2": "Level 2",
+    "level-3": "Level 3",
+    "level-4": "Level 4",
+    "level-5": "Level 5",
+    "level-6": "Level 6",
+    "unknown": "Unknown"
+  },
+  "em-gcs-eye-opening": {
+    "spontaneous": "Spontaneous",
+    "to-voice": "To voice",
+    "to-pain": "To pain",
+    "no-response": "No response"
+  },
+  "em-gcs-motor-response": {
+    "obeys-commands": "Obeys commands",
+    "localizes-pain": "Localizes pain",
+    "withdraws-from-pain": "Withdraws from pain",
+    "flexion-to-pain": "Flexion to pain (decorticate)",
+    "extension-to-pain": "Extension to pain (decerebrate)",
+    "no-response": "No response"
+  },
+  "em-gcs-verbal-response": {
+    "oriented": "Oriented",
+    "confused": "Confused",
+    "inappropriate-words": "Inappropriate words",
+    "incomprehensible-sounds": "Incomprehensible sounds",
+    "no-response": "No response"
+  },
+  "em-id-type": {
+    "national-id": "National ID",
+    "passport": "Passport",
+    "alien-id": "Alien ID",
+    "huduma-namba": "Huduma Namba"
+  },
+  "em-incident-type": {
+    "medical": "Medical emergency",
+    "trauma": "Trauma",
+    "obstetric": "Obstetric emergency",
+    "paediatric": "Paediatric emergency",
+    "mental-health": "Mental health emergency",
+    "mass-casualty": "Mass-casualty incident",
+    "fire": "Fire-related incident",
+    "road-traffic": "Road traffic incident",
+    "interfacility-transfer": "Inter-facility transfer",
+    "other": "Other emergency incident"
+  },
+  "em-investigation": {
+    "em-investigation": "EM Investigation"
+  },
+  "em-investigation-codes": {
+    "2339-0": "Glucose [Mass/volume] in Blood",
+    "25061-3": "US Unspecified body region",
+    "11524-6": "EKG study",
+    "19891-1": "Carbon dioxide [Partial pressure] in Exhaled gas --at end expiration",
+    "52484-3": "Arterial Blood Gases (ABGs)"
+  },
+  "em-observation-category": {
+    "caller-reported": "Caller reported",
+    "emt-assessed": "Emergency practitioner assessed"
+  },
+  "em-observation-code": {
+    "caller-consciousness": "Caller-reported level of consciousness",
+    "caller-breathing": "Caller-reported breathing status",
+    "caller-active-bleeding": "Caller-reported active bleeding"
+  },
+  "em-ownership-type": {
+    "government": "Government",
+    "private": "Private",
+    "ngo": "Non-governmental organization",
+    "other": "Other"
+  },
+  "em-participant-role": {
+    "reporter": "Reporter",
+    "dispatcher": "Dispatcher",
+    "supporting-agency": "Supporting agency",
+    "emt": "EMT / attending clinician"
+  },
+  "em-poc-encounter-type": {
+    "scene-care": "Scene care",
+    "transport-care": "Care during transport",
+    "scene-and-transport": "Scene and transport care",
+    "handover": "Facility handover",
+    "remote-clinical-support": "Remote clinical support"
+  },
+  "em-priority-level-cs": {
+    "low": "Low",
+    "medium": "Medium",
+    "high": "High",
+    "critical": "Critical"
+  },
+  "em-procedure-codes": {
+    "JB": "Drainage",
+    "HTB.MC.AH": "Closed chest cardiac massage",
+    "IDB.DL.AF": "Percutaneous transluminal insertion of device into vein of thorax",
+    "JBA.DL.AC": "Insertion of endotracheal tube",
+    "JZZ.JB.AC": "Suctioning of airways, not elsewhere classified",
+    "JAM.DL.AC": "Insertion of nasopharyngeal airway",
+    "NAI.DL.AD": "Insertion of device into urinary bladder",
+    "PZX.LC.AH": "Application of cast or splint, not elsewhere classified",
+    "JA": "Irrigation",
+    "HFC.SC.AH": "Conversion of cardiac arrhythmia",
+    "HT2.MC.AH": "Cardiopulmonary resuscitation",
+    "IZD.DL.AF": "Percutaneous transluminal insertion of device into vein, not elsewhere classified",
+    "JCB.JB.AE": "Percutaneous drainage of pleural cavity",
+    "JTB.DE.AC": "Artificial ventilation",
+    "KAR.DL.AC": "Insertion of oropharyngeal airway",
+    "KAR.JB.AC": "Oropharyngeal suctioning"
+  },
+  "em-referral-category": {
+    "patient-transport": "Patient Transport",
+    "emergency-evacuation": "Emergency Evacuation"
+  },
+  "em-referral-reason": {
+    "inter-facility": "Inter-facility Transfer",
+    "scene-response": "Scene response and primary evacuation",
+    "repatriation": "Repatriation",
+    "unknown": "Unknown"
+  },
+  "em-responder-unit-type": {
+    "ambulance": "Ambulance",
+    "advanced-life-support": "Advanced life-support ambulance",
+    "basic-life-support": "Basic life-support ambulance",
+    "patient-transport": "Patient transport vehicle",
+    "rapid-response": "Rapid-response vehicle",
+    "motorcycle": "Emergency-response motorcycle",
+    "air-ambulance": "Air ambulance",
+    "boat-ambulance": "Boat ambulance",
+    "command-unit": "Command unit",
+    "other": "Other responder unit"
+  },
+  "em-scene-location-type": {
+    "residence": "Residence",
+    "road": "Road or highway",
+    "workplace": "Workplace",
+    "school": "School or educational institution",
+    "health-facility": "Health facility",
+    "public-place": "Public place",
+    "industrial-site": "Industrial site",
+    "farm": "Farm or agricultural location",
+    "water-body": "Water body",
+    "remote-area": "Remote or difficult-to-access area",
+    "unknown": "Unknown location type",
+    "other": "Other scene location"
+  },
+  "em-secondary-survey-region": {
+    "XA20Q1": "Head",
+    "XA7AA6": "Neck",
+    "XA55T2": "Chest",
+    "XA2P90": "Back and Spine",
+    "XA6GV0": "Abdomen",
+    "XA8Y23": "Pelvis",
+    "XA4BA8": "Upper Extremities",
+    "XA45A6": "Lower Extremities",
+    "XJ652": "Abrasions",
+    "NE2Z": "Burn",
+    "XJ9NV": "Contusion",
+    "LA18225-5": "Deformity",
+    "LA7437-2": "Fracture",
+    "LA7418-2": "Hemorrhage",
+    "LA7452-1": "Laceration",
+    "MG3Z": "Pain",
+    "LA23815-6": "Rigidity",
+    "LA22440-4": "Swelling",
+    "LA17709-9": "Tenderness",
+    "LA6626-1": "Normal Finding",
+    "35088-4": "Glasgow Coma Scale (GCS)",
+    "9267-6": "Eye Opening",
+    "XC3W": "Spontaneous",
+    "XC5L": "To Voice",
+    "XC3H": "To Pain",
+    "XC87": "No Response",
+    "9268-4": "Motor Response",
+    "XC4L": "Obeys Commands",
+    "XC6J": "Localizes Pain",
+    "XC8Q": "Withdraws From Pain",
+    "XC8W": "Flexion to Pain (Decorticate)",
+    "XC8H": "Extension to Pain (Decerebrate)",
+    "XC34": "No Response",
+    "9270-0": "Verbal Response",
+    "XC2X": "Oriented",
+    "XC4Y": "Confused",
+    "XC4A": "Inappropriate Words",
+    "XC7U": "Incomprehensible Sounds",
+    "XC8U": "No Response"
+  },
+  "em-source-gcs-eye-opening": {
+    "XC3W": "Spontaneous",
+    "XC5L": "To Voice",
+    "XC3H": "To Pain",
+    "XC87": "No Response"
+  },
+  "em-source-gcs-motor-response": {
+    "XC87": "Obeys Commands",
+    "XC6J": "Localizes Pain",
+    "XC8Q": "Withdraws From Pain",
+    "XC8W": "Flexion to Pain (Decorticate)",
+    "XC8H": "Extension to Pain (Decerebrate)",
+    "XC34": "No Response"
+  },
+  "em-source-gcs-verbal-response": {
+    "XC2X": "Oriented",
+    "XC4Y": "Confused",
+    "XC4A": "Inappropriate Words",
+    "XC7U": "Incomprehensible Sounds",
+    "XC8U": "No Response"
+  },
+  "em-transport-modality": {
+    "road": "Patient Transport",
+    "emergency-evacuation": "Emergency Evacuation"
+  },
+  "em-unit-response-status": {
+    "dispatched": "Dispatched",
+    "en-route": "En route",
+    "on-scene": "On scene",
+    "transporting": "Transporting",
+    "at-facility": "At facility",
+    "stood-down": "Stood down"
+  },
+  "em-vital-qualitative-state": {
+    "weak": "Weak",
+    "strong": "Strong",
+    "bounding": "Bounding",
+    "thready": "Thready",
+    "regular": "Regular",
+    "irregular": "Irregular",
+    "labored": "Labored",
+    "shallow": "Shallow",
+    "normal": "Normal"
+  },
+  "em-vital-signs-loinc-cs": {
+    "8867-4": "Heart rate",
+    "9279-1": "Respiratory rate",
+    "8310-5": "Body temperature",
+    "59408-5": "Oxygen saturation by pulse oximetry",
+    "2708-6": "Oxygen saturation in arterial blood",
+    "8480-6": "Systolic blood pressure",
+    "8462-4": "Diastolic blood pressure",
+    "8478-0": "Mean blood pressure",
+    "29463-7": "Body weight",
+    "8302-2": "Body height",
+    "39156-5": "Body mass index",
+    "9843-4": "Head circumference",
+    "85353-1": "Vital signs panel",
+    "85354-9": "Blood pressure panel",
+    "9269-2": "Glasgow coma score"
+  }
+}

package/src/shr/shr-terminology.resource.test.ts

@@ -0,0 +1,66 @@
+import { lookupCodeDisplay } from './shr-terminology.resource';
+import { conceptText } from './shr-viewer/shr-presentation';
+
+const UAT = 'https://nshr-uat.sha.go.ke/fhir/CodeSystem';
+
+describe('lookupCodeDisplay', () => {
+  it('resolves a bare vital-sign LOINC code from the bundled code systems', () => {
+    expect(lookupCodeDisplay(`${UAT}/em-vital-signs-loinc-cs`, '8480-6')).toBe('Systolic blood pressure');
+    expect(lookupCodeDisplay(`${UAT}/em-vital-signs-loinc-cs`, '8310-5')).toBe('Body temperature');
+  });
+
+  it('resolves body-region and assessment-finding codes', () => {
+    expect(lookupCodeDisplay(`${UAT}/em-body-region`, 'XA45A6')).toBe('Lower extremities');
+    expect(lookupCodeDisplay(`${UAT}/em-body-assessment-finding`, 'rigidity')).toBe('Rigidity');
+  });
+
+  it('resolves the same system published under a different host, since lookup is keyed by CodeSystem id', () => {
+    // `em-crew-role` is published under `hie.go.ke` in UAT, and every system moves
+    // host again in production. Only the trailing id is stable.
+    expect(lookupCodeDisplay('http://hie.go.ke/fhir/CodeSystem/em-crew-role', 'paramedic')).toBe('Paramedic');
+    expect(lookupCodeDisplay('https://nshr.sha.go.ke/fhir/CodeSystem/em-body-region', 'XA20Q1')).toBe('Head');
+  });
+
+  it('flows through conceptText, matching how the presenters read it', () => {
+    expect(conceptText({ coding: [{ system: `${UAT}/em-body-region`, code: 'XA45A6' }] })).toBe('Lower extremities');
+  });
+
+  it('prefers a display the coding already carries over the bundled one', () => {
+    expect(
+      conceptText({ coding: [{ system: `${UAT}/em-body-region`, code: 'XA45A6', display: 'Already here' }] }),
+    ).toBe('Already here');
+  });
+
+  it('returns undefined for a system we do not carry, so callers fall back to the raw code', () => {
+    expect(lookupCodeDisplay(`${UAT}/not-a-bundled-system`, 'anything')).toBeUndefined();
+  });
+
+  it('returns undefined for a code missing from a system we do carry', () => {
+    expect(lookupCodeDisplay(`${UAT}/em-dispatch-priority`, 'P99')).toBeUndefined();
+  });
+
+  it('returns undefined when either argument is missing', () => {
+    expect(lookupCodeDisplay(undefined, 'P1')).toBeUndefined();
+    expect(lookupCodeDisplay(`${UAT}/em-dispatch-priority`, undefined)).toBeUndefined();
+    expect(lookupCodeDisplay('', '')).toBeUndefined();
+  });
+
+  it('does not resolve a generic terminology system that happens to share a code', () => {
+    expect(lookupCodeDisplay('http://loinc.org', '8480-6')).toBeUndefined();
+  });
+
+  it('only trusts the trailing id when the URL actually names a CodeSystem', () => {
+    // The host and resource type are both discarded, so without this guard a bare
+    // word — or the ValueSet an IG publishes under the same id — would resolve.
+    expect(lookupCodeDisplay('em-body-region', 'XA20Q1')).toBeUndefined();
+    expect(lookupCodeDisplay(`${UAT.replace('/CodeSystem', '/ValueSet')}/em-body-region`, 'XA20Q1')).toBeUndefined();
+    expect(lookupCodeDisplay(`${UAT}/`, 'XA20Q1')).toBeUndefined();
+  });
+
+  it('does not mistake an inherited Object property for a display', () => {
+    // `code` is payload data and can name anything.
+    for (const code of ['constructor', 'toString', 'hasOwnProperty', '__proto__']) {
+      expect(lookupCodeDisplay(`${UAT}/em-body-region`, code)).toBeUndefined();
+    }
+  });
+});

package/src/shr/shr-terminology.resource.ts

@@ -0,0 +1,64 @@
+import codeSystems from './shr-code-systems.json';
+
+/**
+ * Resolver for SHR coding display text.
+ *
+ * Several SHR codings — vital-sign LOINC codes, secondary-survey body-region
+ * and finding codes — arrive with a `code` but no `display` (e.g.
+ * `{ system: "https://nshr-uat.sha.go.ke/fhir/CodeSystem/em-body-region",
+ * code: "XA45A6" }`). The SHR's own convention is that `coding.system` is
+ * itself a resolvable FHIR `CodeSystem` URL, so those displays were once
+ * fetched from it at runtime.
+ *
+ * They can't be. The O3 app shell serves a Content-Security-Policy whose
+ * `connect-src` does not list the SHA FHIR server, so the browser blocks the
+ * request before it is sent — no amount of retrying or CORS cooperation from
+ * the server (which does send `Access-Control-Allow-Origin`) changes that, and
+ * the policy is set by the hosting gateway, not by this module. Every SHR call
+ * that works goes through `openmrsFetch` to the same-origin HIE proxy; there is
+ * no proxy route for arbitrary terminology.
+ *
+ * So the concepts ship with the bundle instead — see
+ * `tools/fetch-shr-code-systems.mjs`, which regenerates
+ * `shr-code-systems.json` from the FHIR server's `em-*` code systems.
+ *
+ * This stays a *display convenience*, never a dependency: a code from a system
+ * we don't carry, or one added upstream since the last regeneration, simply
+ * resolves to `undefined` and callers keep showing the raw code — exactly as
+ * they did when the fetch failed.
+ */
+
+/**
+ * Systems are keyed by CodeSystem **id** — the last segment of the canonical
+ * URL — rather than by the URL itself, because the same system is published
+ * under a different host in each environment (`nshr-uat.sha.go.ke` in UAT,
+ * `hie.go.ke` for a few, another host in production). Keying on the id makes a
+ * single bundled copy correct everywhere.
+ */
+const conceptsBySystemId: Record<string, Record<string, string>> = codeSystems;
+
+/**
+ * Discarding the host also discards the resource type, so require the URL to
+ * name a CodeSystem before trusting its last segment. Without this, a bare word
+ * (`"em-body-region"`) or the ValueSet an IG conventionally publishes under the
+ * same id (`.../fhir/ValueSet/em-body-region`) would resolve against the code
+ * system's concepts.
+ */
+const CODE_SYSTEM_URL_PATTERN = /\/CodeSystem\/[^/]/;
+
+/** `.../fhir/CodeSystem/em-body-region` → `em-body-region`. Mirrored in the generator. */
+function codeSystemId(system: string): string | undefined {
+  return system.split('/').filter(Boolean).pop();
+}
+
+/** A code's display, if we carry its code system and the code is in it. */
+export function lookupCodeDisplay(system?: string, code?: string): string | undefined {
+  if (!system || !code || !CODE_SYSTEM_URL_PATTERN.test(system)) {
+    return undefined;
+  }
+  const id = codeSystemId(system);
+  const display = id ? conceptsBySystemId[id]?.[code] : undefined;
+  // `code` is payload data, so it can name something inherited from
+  // `Object.prototype` (`constructor`, `toString`); those are not displays.
+  return typeof display === 'string' ? display : undefined;
+}