@ohmaorg/esm-billing-commons 1.0.1

package/package.json

@@ -0,0 +1 @@
+{"name":"@ohmaorg/esm-billing-commons","version":"1.0.1","private":false,"main":"src/index.ts","types":"src/index.ts","scripts":{"typecheck":"tsc --noEmit","lint":"echo 'lint ok'","test":"echo 'no tests yet'","build":"echo 'commons build ok'"},"peerDependencies":{"@openmrs/esm-framework":">=5.0.0","react":"18.x","swr":"2.x","@carbon/react":"^1.0.0"},"devDependencies":{"@openmrs/esm-framework":"^5.0.0","@carbon/react":"^1.71.0","react":"^18.3.1","react-dom":"^18.3.1","react-i18next":"^16.5.0","i18next":"^25.0.0","swr":"^2.2.5","dayjs":"^1.11.0","rxjs":"^6.6.0","single-spa":"^6.0.0","@types/react":"^18.3.0","typescript":"~5.4.0"},"files":["src","package.json"]}

package/src/api.ts

@@ -0,0 +1,124 @@
+/**
+ * API helper functions for mutating data (POST, DELETE) via openmrsFetch.
+ * SWR hooks handle reads; these handle writes.
+ */
+import { openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import {
+  BILL_REST_URL,
+  CLAIM_REST_URL,
+  EDI_PROCESS_URL,
+  EDI_RETRY_URL,
+  TARIFF_REST_URL,
+} from './constants';
+import type { Bill, Claim, EdiProcessResult, Tariff } from './types';
+
+// --- Bill API ---
+
+export function createBill(payload: {
+  patient: string;
+  encounter?: string;
+  payerIdentifier?: string;
+  billItems?: Array<{
+    serviceOrItem?: string;
+    description?: string;
+    quantity: number;
+    unitPrice: number;
+  }>;
+}): Promise<Bill> {
+  return openmrsFetch(`${restBaseUrl}${BILL_REST_URL}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: payload,
+  }).then((res) => res.data);
+}
+
+export function updateBill(
+  uuid: string,
+  payload: { status?: string; payerIdentifier?: string },
+): Promise<Bill> {
+  return openmrsFetch(`${restBaseUrl}${BILL_REST_URL}/${uuid}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: payload,
+  }).then((res) => res.data);
+}
+
+export function voidBill(uuid: string, reason: string): Promise<void> {
+  return openmrsFetch(
+    `${restBaseUrl}${BILL_REST_URL}/${uuid}?reason=${encodeURIComponent(reason)}`,
+    { method: 'DELETE' },
+  ).then(() => undefined);
+}
+
+// --- Tariff API ---
+
+export function createTariff(payload: {
+  name: string;
+  description?: string;
+  serviceOrItem?: string;
+  unitPrice: number;
+  currency?: string;
+  effectiveFrom?: string;
+  effectiveTo?: string;
+}): Promise<Tariff> {
+  return openmrsFetch(`${restBaseUrl}${TARIFF_REST_URL}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: payload,
+  }).then((res) => res.data);
+}
+
+export function retireTariff(uuid: string, reason: string): Promise<void> {
+  return openmrsFetch(
+    `${restBaseUrl}${TARIFF_REST_URL}/${uuid}?reason=${encodeURIComponent(reason)}`,
+    { method: 'DELETE' },
+  ).then(() => undefined);
+}
+
+// --- Claim API ---
+
+export function createClaimFromBill(billUuid: string): Promise<Claim> {
+  return openmrsFetch(`${restBaseUrl}${CLAIM_REST_URL}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: { billUuid },
+  }).then((res) => res.data);
+}
+
+export function updateClaim(
+  uuid: string,
+  payload: {
+    status?: string;
+    approvedAmount?: number;
+    paidAmount?: number;
+    rejectionReason?: string;
+  },
+): Promise<Claim> {
+  return openmrsFetch(`${restBaseUrl}${CLAIM_REST_URL}/${uuid}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: payload,
+  }).then((res) => res.data);
+}
+
+export function voidClaim(uuid: string, reason: string): Promise<void> {
+  return openmrsFetch(
+    `${restBaseUrl}${CLAIM_REST_URL}/${uuid}?reason=${encodeURIComponent(reason)}`,
+    { method: 'DELETE' },
+  ).then(() => undefined);
+}
+
+// --- EDI API ---
+
+export function processClaimEdi(claimUuid: string): Promise<EdiProcessResult> {
+  return openmrsFetch(
+    `${restBaseUrl}${EDI_PROCESS_URL}?claimUuid=${encodeURIComponent(claimUuid)}`,
+    { method: 'POST' },
+  ).then((res) => res.data);
+}
+
+export function retryEdiTransaction(transactionUuid: string): Promise<EdiProcessResult> {
+  return openmrsFetch(`${restBaseUrl}${EDI_RETRY_URL}/${transactionUuid}`, {
+    method: 'POST',
+  }).then((res) => res.data);
+}

package/src/constants.ts

@@ -0,0 +1,78 @@
+/**
+ * REST endpoint paths and shared constants for Billing, Claims, and EDI modules.
+ * All paths are relative to the OpenMRS API base URL (e.g. /openmrs).
+ */
+
+// --- REST paths ---
+
+export const REST_BASE = '/ws/rest/v1';
+
+export const BILL_REST_URL = `${REST_BASE}/bill`;
+export const TARIFF_REST_URL = `${REST_BASE}/tariff`;
+export const CLAIM_REST_URL = `${REST_BASE}/claim`;
+
+export const EDI_BASE_URL = `${REST_BASE}/edi`;
+export const EDI_PROCESS_URL = `${EDI_BASE_URL}/process`;
+export const EDI_RETRY_URL = `${EDI_BASE_URL}/retry`;
+export const EDI_TRANSACTION_URL = `${EDI_BASE_URL}/transaction`;
+export const EDI_TRANSACTIONS_URL = `${EDI_BASE_URL}/transactions`;
+export const EDI_PAYERS_URL = `${EDI_BASE_URL}/payers`;
+export const EDI_FORMATS_URL = `${EDI_BASE_URL}/formats`;
+export const EDI_EXPORT_STATUS_URL = `${EDI_BASE_URL}/export/status`;
+export const EDI_SUMMARY_URL = `${EDI_BASE_URL}/summary`;
+
+// --- Status display colors (Carbon token names) ---
+
+export const BILL_STATUS_COLORS: Record<string, string> = {
+  DRAFT: 'blue',
+  FINAL: 'green',
+  VOIDED: 'gray',
+};
+
+export const CLAIM_STATUS_COLORS: Record<string, string> = {
+  DRAFT: 'blue',
+  SUBMITTED: 'cyan',
+  ACCEPTED: 'green',
+  REJECTED: 'red',
+  PARTIALLY_PAID: 'yellow',
+  PAID: 'green',
+};
+
+export const EDI_STATUS_COLORS: Record<string, string> = {
+  PENDING: 'blue',
+  PROCESSING: 'cyan',
+  SENT: 'green',
+  ACCEPTED: 'green',
+  REJECTED: 'red',
+  FAILED: 'red',
+  RETRY_PENDING: 'yellow',
+};
+
+// --- Privilege names ---
+
+export const PRIVILEGES = {
+  VIEW_BILLS: 'View Bills',
+  EDIT_BILLS: 'Edit Bills',
+  FINALIZE_BILLS: 'Finalize Bills',
+  VOID_BILLS: 'Void Bills',
+  RECORD_PAYMENTS: 'Record Payments',
+  MANAGE_TARIFFS: 'Manage Tariffs',
+  VIEW_CLAIMS: 'View Claims',
+  CREATE_CLAIMS: 'Create Claims',
+  SUBMIT_CLAIMS: 'Submit Claims',
+  MANAGE_CLAIMS: 'Manage Claims',
+  EXPORT_EDI: 'Export EDI',
+  RETRY_EDI: 'Retry EDI Submission',
+  VIEW_EDI_AUDIT: 'View EDI Audit',
+} as const;
+
+// --- Module names ---
+
+export const BILLING_MODULE_NAME = '@ohmaorg/esm-billing-app';
+export const CLAIMS_MODULE_NAME = '@ohmaorg/esm-claims-app';
+export const EDI_MODULE_NAME = '@ohmaorg/esm-edi-app';
+
+// --- Default currency ---
+
+export const DEFAULT_CURRENCY = 'BWP';
+export const DEFAULT_CURRENCY_SYMBOL = 'P';

package/src/hooks.ts

@@ -0,0 +1,150 @@
+/**
+ * Shared SWR hooks for fetching billing, claims, and EDI data from the REST API.
+ * Each hook uses the openmrsFetch utility from @openmrs/esm-framework.
+ */
+import { openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import useSWR from 'swr';
+import type {
+  Bill,
+  Claim,
+  EdiTransaction,
+  EdiTransactionSummary,
+  PaginatedResponse,
+} from './types';
+import {
+  BILL_REST_URL,
+  CLAIM_REST_URL,
+  EDI_SUMMARY_URL,
+  EDI_TRANSACTION_URL,
+  EDI_TRANSACTIONS_URL,
+  TARIFF_REST_URL,
+} from './constants';
+import type { Tariff } from './types';
+
+interface FetchResponse<T> {
+  data: T;
+}
+
+function swrFetcher<T>(url: string): Promise<T> {
+  return openmrsFetch(url).then((res: FetchResponse<T>) => res.data);
+}
+
+// --- Bill hooks ---
+
+export interface UseBillsOptions {
+  status?: string;
+  patient?: string;
+  fromDate?: string;
+  toDate?: string;
+  startIndex?: number;
+  limit?: number;
+}
+
+export function useBills(options: UseBillsOptions = {}) {
+  const params = new URLSearchParams();
+  if (options.status) params.set('status', options.status);
+  if (options.patient) params.set('patient', options.patient);
+  if (options.fromDate) params.set('fromDate', options.fromDate);
+  if (options.toDate) params.set('toDate', options.toDate);
+  if (options.startIndex != null) params.set('startIndex', String(options.startIndex));
+  if (options.limit != null) params.set('limit', String(options.limit));
+
+  const query = params.toString();
+  const hasSearchParams = options.status || options.patient || options.fromDate || options.toDate;
+  const baseUrl = hasSearchParams ? `${BILL_REST_URL}?${query}` : `${BILL_REST_URL}?${query}`;
+
+  return useSWR<PaginatedResponse<Bill>>(
+    `${restBaseUrl}${baseUrl.startsWith('/') ? baseUrl.slice(1) : baseUrl}`,
+    swrFetcher,
+  );
+}
+
+export function useBill(uuid: string | null | undefined) {
+  const url = uuid ? `${restBaseUrl}${BILL_REST_URL}/${uuid}?v=full` : null;
+  return useSWR<Bill>(url, swrFetcher);
+}
+
+// --- Tariff hooks ---
+
+export function useTariffs(includeRetired = false) {
+  const url = includeRetired
+    ? `${restBaseUrl}${TARIFF_REST_URL}?includeAll=true`
+    : `${restBaseUrl}${TARIFF_REST_URL}`;
+
+  return useSWR<PaginatedResponse<Tariff>>(url, swrFetcher);
+}
+
+export function useTariff(uuid: string | null | undefined) {
+  const url = uuid ? `${restBaseUrl}${TARIFF_REST_URL}/${uuid}?v=full` : null;
+  return useSWR<Tariff>(url, swrFetcher);
+}
+
+// --- Claim hooks ---
+
+export interface UseClaimsOptions {
+  status?: string;
+  patient?: string;
+  payerIdentifier?: string;
+  startIndex?: number;
+  limit?: number;
+}
+
+export function useClaims(options: UseClaimsOptions = {}) {
+  const params = new URLSearchParams();
+  if (options.status) params.set('status', options.status);
+  if (options.patient) params.set('patient', options.patient);
+  if (options.payerIdentifier) params.set('payerIdentifier', options.payerIdentifier);
+  if (options.startIndex != null) params.set('startIndex', String(options.startIndex));
+  if (options.limit != null) params.set('limit', String(options.limit));
+
+  const query = params.toString();
+  const baseUrl = `${CLAIM_REST_URL}?${query}`;
+
+  return useSWR<PaginatedResponse<Claim>>(
+    `${restBaseUrl}${baseUrl.startsWith('/') ? baseUrl.slice(1) : baseUrl}`,
+    swrFetcher,
+  );
+}
+
+export function useClaim(uuid: string | null | undefined) {
+  const url = uuid ? `${restBaseUrl}${CLAIM_REST_URL}/${uuid}?v=full` : null;
+  return useSWR<Claim>(url, swrFetcher);
+}
+
+// --- EDI hooks ---
+
+export function useEdiTransaction(uuid: string | null | undefined) {
+  const url = uuid ? `${restBaseUrl}${EDI_TRANSACTION_URL}/${uuid}` : null;
+  return useSWR<EdiTransaction>(url, swrFetcher);
+}
+
+export interface UseEdiTransactionsOptions {
+  claimUuid?: string;
+  status?: string;
+  payerCode?: string;
+  fromDate?: string;
+  toDate?: string;
+  startIndex?: number;
+  limit?: number;
+}
+
+export function useEdiTransactions(options: UseEdiTransactionsOptions = {}) {
+  const params = new URLSearchParams();
+  if (options.claimUuid) params.set('claimUuid', options.claimUuid);
+  if (options.status) params.set('status', options.status);
+  if (options.payerCode) params.set('payerCode', options.payerCode);
+  if (options.fromDate) params.set('fromDate', options.fromDate);
+  if (options.toDate) params.set('toDate', options.toDate);
+  if (options.startIndex != null) params.set('startIndex', String(options.startIndex));
+  if (options.limit != null) params.set('limit', String(options.limit));
+
+  const query = params.toString();
+  return useSWR<PaginatedResponse<EdiTransaction>>(
+    `${restBaseUrl}${EDI_TRANSACTIONS_URL}?${query}`,
+    swrFetcher,
+  );
+}
+
+export function useEdiSummary() {
+  return useSWR<EdiTransactionSummary>(`${restBaseUrl}${EDI_SUMMARY_URL}`, swrFetcher);
+}

package/src/index.ts

@@ -0,0 +1,85 @@
+// Public API for @ohmaorg/esm-billing-commons
+
+// Types
+export type {
+  Bill,
+  BillItem,
+  BillStatus,
+  Payment,
+  PaymentMode,
+  Adjustment,
+  Tariff,
+  Claim,
+  ClaimLine,
+  ClaimStatus,
+  EdiTransaction,
+  EdiTransactionStatus,
+  EdiProcessResult,
+  EdiTransactionSummary,
+  PaginatedResponse,
+  PatientRef,
+  ConceptRef,
+  EncounterRef,
+  AuditInfo,
+  OpenmrsResource,
+} from './types';
+
+// Constants
+export {
+  REST_BASE,
+  BILL_REST_URL,
+  TARIFF_REST_URL,
+  CLAIM_REST_URL,
+  EDI_BASE_URL,
+  EDI_PROCESS_URL,
+  EDI_RETRY_URL,
+  EDI_TRANSACTION_URL,
+  EDI_TRANSACTIONS_URL,
+  EDI_PAYERS_URL,
+  EDI_FORMATS_URL,
+  EDI_EXPORT_STATUS_URL,
+  EDI_SUMMARY_URL,
+  BILL_STATUS_COLORS,
+  CLAIM_STATUS_COLORS,
+  EDI_STATUS_COLORS,
+  PRIVILEGES,
+  BILLING_MODULE_NAME,
+  CLAIMS_MODULE_NAME,
+  EDI_MODULE_NAME,
+  DEFAULT_CURRENCY,
+  DEFAULT_CURRENCY_SYMBOL,
+} from './constants';
+
+// Hooks
+export {
+  useBills,
+  useBill,
+  useTariffs,
+  useTariff,
+  useClaims,
+  useClaim,
+  useEdiTransaction,
+  useEdiTransactions,
+  useEdiSummary,
+} from './hooks';
+export type { UseBillsOptions, UseClaimsOptions, UseEdiTransactionsOptions } from './hooks';
+
+// API (mutation helpers)
+export {
+  createBill,
+  updateBill,
+  voidBill,
+  createTariff,
+  retireTariff,
+  createClaimFromBill,
+  updateClaim,
+  voidClaim,
+  processClaimEdi,
+  retryEdiTransaction,
+} from './api';
+
+// Utils
+export { formatCurrency, formatDate, getPatientName } from './utils';
+
+// Components
+export { default as StatusBadge } from './status-badge.component';

package/src/status-badge.component.tsx

@@ -0,0 +1,68 @@
+import React from 'react';
+import { Tag } from '@carbon/react';
+import {
+  BILL_STATUS_COLORS,
+  CLAIM_STATUS_COLORS,
+  EDI_STATUS_COLORS,
+} from './constants';
+
+type StatusDomain = 'bill' | 'claim' | 'edi';
+
+const COLOR_MAPS: Record<StatusDomain, Record<string, string>> = {
+  bill: BILL_STATUS_COLORS,
+  claim: CLAIM_STATUS_COLORS,
+  edi: EDI_STATUS_COLORS,
+};
+
+const VALID_TAG_TYPES = [
+  'red',
+  'magenta',
+  'purple',
+  'blue',
+  'cyan',
+  'teal',
+  'green',
+  'gray',
+  'cool-gray',
+  'warm-gray',
+  'high-contrast',
+  'outline',
+] as const;
+
+type TagType = (typeof VALID_TAG_TYPES)[number];
+
+const COLOR_TO_TAG_TYPE: Record<string, TagType> = {
+  red: 'red',
+  blue: 'blue',
+  cyan: 'cyan',
+  green: 'green',
+  gray: 'gray',
+  yellow: 'warm-gray',
+};
+
+const DEFAULT_TAG_TYPE: TagType = 'gray';
+
+interface StatusBadgeProps {
+  status: string;
+  domain: StatusDomain;
+}
+
+/**
+ * Reusable badge component that maps a bill/claim/EDI status
+ * to a colored Carbon Tag. The domain determines which color
+ * mapping to use.
+ */
+const StatusBadge: React.FC<StatusBadgeProps> = ({ status, domain }) => {
+  const colorMap = COLOR_MAPS[domain] ?? {};
+  const colorName = colorMap[status] ?? 'gray';
+  const tagType: TagType = COLOR_TO_TAG_TYPE[colorName] ?? DEFAULT_TAG_TYPE;
+  const label = status.replace(/_/g, ' ');
+
+  return (
+    <Tag type={tagType} size="sm">
+      {label}
+    </Tag>
+  );
+};
+
+export default StatusBadge;

package/src/types.ts

@@ -0,0 +1,180 @@
+/**
+ * TypeScript interfaces matching the OpenMRS REST resource representations
+ * for the Billing, Claims, and EDI modules.
+ */
+
+// --- Common OpenMRS types ---
+
+export interface OpenmrsResource {
+  uuid: string;
+  display?: string;
+  links?: Array<{ rel: string; uri: string; resourceAlias?: string }>;
+}
+
+export interface PatientRef extends OpenmrsResource {
+  identifiers?: Array<{ identifier: string; display: string }>;
+}
+
+export interface ConceptRef extends OpenmrsResource {
+  name?: { display: string };
+}
+
+export interface EncounterRef extends OpenmrsResource {
+  encounterDatetime?: string;
+  encounterType?: { display: string };
+}
+
+export interface AuditInfo {
+  creator: OpenmrsResource;
+  dateCreated: string;
+  changedBy?: OpenmrsResource;
+  dateChanged?: string;
+}
+
+// --- Billing types ---
+
+export type BillStatus = 'DRAFT' | 'FINAL' | 'VOIDED';
+
+export type PaymentMode =
+  | 'CASH'
+  | 'MEDICAL_AID'
+  | 'BANK_TRANSFER'
+  | 'CARD'
+  | 'CHEQUE'
+  | 'OTHER';
+
+export interface BillItem extends OpenmrsResource {
+  serviceOrItem?: ConceptRef;
+  description?: string;
+  quantity: number;
+  unitPrice: number;
+  lineTotal: number;
+}
+
+export interface Payment extends OpenmrsResource {
+  amount: number;
+  paymentMode: PaymentMode;
+  referenceNumber?: string;
+  paymentDate: string;
+}
+
+export interface Adjustment extends OpenmrsResource {
+  amount: number;
+  reason: string;
+  billItem?: BillItem;
+}
+
+export interface Bill extends OpenmrsResource {
+  status: BillStatus;
+  currency: string;
+  totalAmount: number;
+  payerIdentifier?: string;
+  billDate: string;
+  patient: PatientRef;
+  encounter?: EncounterRef;
+  billItems?: BillItem[];
+  payments?: Payment[];
+  adjustments?: Adjustment[];
+  voided?: boolean;
+  voidReason?: string;
+  auditInfo?: AuditInfo;
+}
+
+export interface Tariff extends OpenmrsResource {
+  name: string;
+  description?: string;
+  serviceOrItem?: ConceptRef;
+  unitPrice: number;
+  currency: string;
+  effectiveFrom?: string;
+  effectiveTo?: string;
+  retired?: boolean;
+  retireReason?: string;
+  auditInfo?: AuditInfo;
+}
+
+// --- Claims types ---
+
+export type ClaimStatus =
+  | 'DRAFT'
+  | 'SUBMITTED'
+  | 'ACCEPTED'
+  | 'REJECTED'
+  | 'PARTIALLY_PAID'
+  | 'PAID';
+
+export interface ClaimLine extends OpenmrsResource {
+  serviceCode?: string;
+  description?: string;
+  quantity: number;
+  amount: number;
+}
+
+export interface Claim extends OpenmrsResource {
+  claimNumber: string;
+  billUuid: string;
+  status: ClaimStatus;
+  claimedAmount: number;
+  approvedAmount?: number;
+  paidAmount?: number;
+  currency: string;
+  payerIdentifier?: string;
+  claimDate: string;
+  submissionDate?: string;
+  rejectionReason?: string;
+  patient: PatientRef;
+  claimLines?: ClaimLine[];
+  voided?: boolean;
+  voidReason?: string;
+  auditInfo?: AuditInfo;
+}
+
+// --- EDI types ---
+
+export type EdiTransactionStatus =
+  | 'PENDING'
+  | 'PROCESSING'
+  | 'SENT'
+  | 'ACCEPTED'
+  | 'REJECTED'
+  | 'FAILED'
+  | 'RETRY_PENDING';
+
+export interface EdiTransaction {
+  uuid: string;
+  claimUuid: string;
+  payerCode: string;
+  status: EdiTransactionStatus;
+  totalAmount: number;
+  currency: string;
+  attemptCount: number;
+  maxAttempts: number;
+  idempotencyKey: string;
+  sentAt?: string;
+  nextRetryAt?: string;
+}
+
+export interface EdiProcessResult {
+  success: boolean;
+  transactionUuid?: string;
+  status?: string;
+  errorMessage?: string;
+}
+
+export interface EdiTransactionSummary {
+  PENDING: number;
+  PROCESSING: number;
+  SENT: number;
+  ACCEPTED: number;
+  REJECTED: number;
+  FAILED: number;
+  RETRY_PENDING: number;
+}
+
+// --- Paginated response ---
+
+export interface PaginatedResponse<T> {
+  results: T[];
+  totalCount?: number;
+  links?: Array<{ rel: string; uri: string }>;
+}

package/src/utils.ts

@@ -0,0 +1,70 @@
+import { DEFAULT_CURRENCY, DEFAULT_CURRENCY_SYMBOL } from './constants';
+
+const CURRENCY_SYMBOLS: Record<string, string> = {
+  BWP: 'P',
+  USD: '$',
+  EUR: '€',
+  GBP: '£',
+  ZAR: 'R',
+};
+
+const MINIMUM_DISPLAY_DECIMALS = 2;
+const MAXIMUM_DISPLAY_DECIMALS = 2;
+
+/**
+ * Format a monetary amount for display using the appropriate currency symbol.
+ * Falls back to the ISO currency code if no symbol mapping exists.
+ *
+ * @param amount - The numeric amount to format
+ * @param currencyCode - ISO 4217 currency code (defaults to BWP)
+ * @returns Formatted string, e.g. "P 1,234.56"
+ */
+export function formatCurrency(
+  amount: number | null | undefined,
+  currencyCode: string = DEFAULT_CURRENCY,
+): string {
+  if (amount == null || isNaN(amount)) {
+    return `${CURRENCY_SYMBOLS[currencyCode] ?? currencyCode} 0.00`;
+  }
+
+  const symbol = CURRENCY_SYMBOLS[currencyCode] ?? currencyCode;
+  const formatted = amount.toLocaleString('en-US', {
+    minimumFractionDigits: MINIMUM_DISPLAY_DECIMALS,
+    maximumFractionDigits: MAXIMUM_DISPLAY_DECIMALS,
+  });
+
+  return `${symbol} ${formatted}`;
+}
+
+/**
+ * Format an ISO date string to a localized display date.
+ *
+ * @param isoDate - ISO 8601 date string
+ * @returns Formatted date string, e.g. "15 Feb 2026"
+ */
+export function formatDate(isoDate: string | null | undefined): string {
+  if (!isoDate) {
+    return '—';
+  }
+
+  const date = new Date(isoDate);
+  if (isNaN(date.getTime())) {
+    return '—';
+  }
+
+  return date.toLocaleDateString('en-GB', {
+    day: 'numeric',
+    month: 'short',
+    year: 'numeric',
+  });
+}
+
+/**
+ * Get a patient display name from a patient reference object.
+ *
+ * @param patient - Patient reference with optional display field
+ * @returns Display name or "Unknown" if not available
+ */
+export function getPatientName(patient: { display?: string } | null | undefined): string {
+  return patient?.display ?? 'Unknown';
+}