@palladium-ethiopia/esm-billing-app 5.4.2-pre.30

package/src/config-schema.ts

@@ -0,0 +1,248 @@
+import { ConfigSchema, Type } from '@openmrs/esm-framework';
+
+export interface BillingConfig {
+  visitAttributeTypes: {
+    isPatientExempted: string;
+    paymentMethods: string;
+    insuranceScheme: string;
+    policyNumber: string;
+    exemptionCategory: string;
+    billPaymentStatus: string;
+    shaBenefitPackagesAndInterventions: string;
+  };
+  insurancePaymentMethod: string;
+  inPatientVisitTypeUuid: string;
+  patientExemptionCategories: Array<{ value: string; label: string }>;
+  excludedPaymentMode: Array<{ uuid: string; label: string }>;
+  enforceBillPayment: boolean;
+  billingStatusQueryUrl: string;
+  mpesaAPIBaseUrl: string;
+  hieBaseUrl: string;
+  insuranceSchemes: Array<string>;
+  shaIdentificationNumberUUID: string;
+  cashPointUuid: string;
+  cashierUuid: string;
+  patientBillsUrl: string;
+  nationalIdUUID: string;
+  isPDSLFacility: boolean;
+  mobileMoneyPaymentModeUUID: string;
+  concepts: {
+    emergencyPriorityConceptUuid: string;
+  };
+  paymentMethodsUuidsThatShouldNotShowPrompt: Array<string>;
+  promptDuration: {
+    enable: boolean;
+    duration: number;
+  };
+  localeCurrencyMapping: Record<string, string>;
+  phoneNumberAttributeTypeUUID: string;
+  nationalIdIdentifierTypeUUID: string;
+  enableClaims: boolean;
+  enablePreAuth: boolean;
+}
+
+export const configSchema: ConfigSchema = {
+  isPDSLFacility: {
+    _type: Type.Boolean,
+    _description: 'A flag for PDSL facilities',
+    _default: false,
+  },
+  mobileMoneyPaymentModeUUID: {
+    _type: Type.UUID,
+    _description: 'Mobile money payment method uuid',
+    _default: '28989582-e8c3-46b0-96d0-c249cb06d5c6',
+  },
+  shaIdentificationNumberUUID: {
+    _type: Type.String,
+    _description: 'Social Health Authority Identification Number',
+    _default: '24aedd37-b5be-4e08-8311-3721b8d5100d',
+  },
+  nationalIdUUID: {
+    _type: Type.String,
+    _description: 'National Identification Number',
+    _default: '49af6cdc-7968-4abb-bf46-de10d7f4859f',
+  },
+  inPatientVisitTypeUuid: {
+    _type: Type.String,
+    _description: 'The visit type uuid for in-patient',
+    _default: 'a73e2ac6-263b-47fc-99fc-e0f2c09fc914',
+  },
+  mpesaAPIBaseUrl: {
+    _type: Type.String,
+    _description: 'The base url that will be used to make any backend calls related to mpesa.',
+    _default: 'https://billing.kenyahmis.org',
+  },
+  phoneNumberAttributeTypeUUID: {
+    _type: Type.String,
+    _description: 'The person attribute type uuid for phone number',
+    _default: 'b2c38640-2603-4629-aebd-3b54f33f1e3a',
+  },
+  nationalIdIdentifierTypeUUID: {
+    _type: Type.String,
+    _description: 'The person attribute type uuid for national id',
+    _default: '49af6cdc-7968-4abb-bf46-de10d7f4859f',
+  },
+  hieBaseUrl: {
+    _type: Type.String,
+    _description: 'HIE Base URL for getting interventions and benefit packages',
+    _default: 'https://payers.apeiro-digital.com/api/v1',
+  },
+  visitAttributeTypes: {
+    isPatientExempted: {
+      _type: Type.String,
+      _default: '3b9dfac8-9e4d-11ee-8c90-0242ac120002',
+      _description: 'Whether the patient should be exempted from paying for service i.e Prisoners',
+    },
+    paymentMethods: {
+      _type: Type.String,
+      _description: 'The payment methods visit attribute uuid',
+      _default: 'e6cb0c3b-04b0-4117-9bc6-ce24adbda802',
+    },
+    insuranceScheme: {
+      _type: Type.String,
+      _description: 'The insurance scheme visit attribute uuid',
+      _default: '2d0fa959-6780-41f1-85b1-402045935068',
+    },
+    policyNumber: {
+      _type: Type.String,
+      _description: 'The policy number visit attribute uuid',
+      _default: '0f4f3306-f01b-43c6-af5b-fdb60015cb02',
+    },
+    exemptionCategory: {
+      _type: Type.String,
+      _description: 'The exemption category visit attribute uuid',
+      _default: 'df0362f9-782e-4d92-8bb2-3112e9e9eb3c',
+    },
+    billPaymentStatus: {
+      _type: Type.String,
+      _description: 'The bill payment status visit attribute uuid',
+      _default: '919b51c9-8e2e-468f-8354-181bf3e55786',
+    },
+    shaBenefitPackagesAndInterventions: {
+      _type: Type.String,
+      _description: 'JSON String of SHA Benefit Packages and Interventions for this visit',
+      _default: '338725fa-3790-4679-98b9-be623214ee29',
+    },
+  },
+  insurancePaymentMethod: {
+    _type: Type.String,
+    _description: 'Insurance Payment method UUID',
+    _default: 'beac329b-f1dc-4a33-9e7c-d95821a137a6',
+  },
+  patientExemptionCategories: {
+    _type: Type.Array,
+    _elements: {
+      value: {
+        _type: Type.String,
+        _description: 'The value of the exemption category',
+      },
+      label: {
+        _type: Type.String,
+        _default: null,
+        _description: 'The label of the exemption category',
+      },
+    },
+    _default: [{ value: 'IN_PRISON', label: 'In Prison' }],
+  },
+  excludedPaymentMode: {
+    _type: Type.Array,
+    _elements: {
+      uuid: {
+        _type: Type.UUID,
+        _description: 'The value of the payment mode to be excluded',
+      },
+      label: {
+        _type: Type.String,
+        _default: null,
+        _description: 'The label of the payment mode to be excluded',
+      },
+    },
+    _default: [
+      {
+        uuid: 'eb6173cb-9678-4614-bbe1-0ccf7ed9d1d4',
+        label: 'Waiver',
+      },
+    ],
+  },
+  enforceBillPayment: {
+    _type: Type.Boolean,
+    _default: true,
+    _description: 'Whether to enforce bill payment or not for patient to receive service',
+  },
+  billingStatusQueryUrl: {
+    _type: Type.String,
+    _default: '${restBaseUrl}/cashier/billLineItem?orderUuid=${orderUuid}&v=full',
+    _description: 'URL to query billing status',
+  },
+  insuranceSchemes: {
+    _type: Type.Array,
+    _elements: {
+      _type: Type.String,
+    },
+    _default: ['SHA', 'Jubilee Insurance', 'AAR Insurance', 'Old Mutual Insurance'],
+    _description: 'List of insurance schemes',
+  },
+  cashPointUuid: {
+    _type: Type.String,
+    _description: 'Where bill is generated from',
+    _default: '54065383-b4d4-42d2-af4d-d250a1fd2590',
+  },
+  cashierUuid: {
+    _type: Type.String,
+    _description: 'Who Generated the bill',
+    _default: '54065383-b4d4-42d2-af4d-d250a1fd2590',
+  },
+  patientBillsUrl: {
+    _type: Type.String,
+    _description: 'The url to fetch patient bills',
+    _default:
+      '${restBaseUrl}/cashier/bill?v=custom:(uuid,display,voided,voidReason,adjustedBy,cashPoint:(uuid,name),cashier:(uuid,display),dateCreated,lineItems,patient:(uuid,display))',
+  },
+  concepts: {
+    emergencyPriorityConceptUuid: {
+      _type: Type.String,
+      _description: 'The concept uuid for emergency priority',
+      _default: '037446f4-adfc-40b3-928c-a39a4826b1bf',
+    },
+  },
+  paymentMethodsUuidsThatShouldNotShowPrompt: {
+    _type: Type.Array,
+    _description: 'The payment methods that should not show the billing prompt',
+    _elements: {
+      _type: Type.String,
+    },
+    _default: ['beac329b-f1dc-4a33-9e7c-d95821a137a6'],
+  },
+  promptDuration: {
+    _type: Type.Object,
+    _description:
+      'The duration in hours for the prompt to be shown, if the duration is less than this, the prompt will be shown',
+    _default: {
+      enable: true,
+      duration: 24,
+    },
+  },
+  localeCurrencyMapping: {
+    _type: Type.Object,
+    _description: 'Mapping of locale codes to currency codes for internationalization',
+    _default: {
+      en: 'KES',
+      sw: 'KES',
+      am: 'ETB',
+      'en-KE': 'KES',
+      'sw-KE': 'KES',
+      'am-ET': 'ETB',
+      'en-GB': 'KES',
+    },
+  },
+  enableClaims: {
+    _type: Type.Boolean,
+    _default: false,
+    _description: 'Whether to enable claims or not',
+  },
+  enablePreAuth: {
+    _type: Type.Boolean,
+    _default: false,
+    _description: 'Whether to enable pre-auth or not',
+  },
+};

package/src/constants.ts

@@ -0,0 +1,24 @@
+export const PENDING_PAYMENT_STATUS = 'PENDING';
+export const EXEMPTED_PAYMENT_STATUS = 'EXEMPTED';
+export const spaBasePath = `${window.spaBase}/home`;
+export const billingAdminBasePath = `${window.spaBase}/billing-admin`;
+
+export const colorsArray = [
+  'red',
+  'magenta',
+  'purple',
+  'blue',
+  'cyan',
+  'teal',
+  'green',
+  'gray',
+  'cool-gray',
+  'warm-gray',
+  'high-contrast',
+  'outline',
+];
+
+// Size in MegaBits
+export const MAX_ALLOWED_FILE_SIZE = 2097152;
+export const PAYMENT_MODE_ATTRIBUTE_FORMATS = ['java.lang.String', 'java.lang.Integer', 'java.lang.Double'];
+export const SHA_INSURANCE_SCHEME = 'SHA';

package/src/dashboard.meta.ts

@@ -0,0 +1,25 @@
+export const dashboardMeta = {
+  slot: 'patient-chart-billing-dashboard-slot',
+  columns: 1,
+  title: 'Billing',
+  path: 'Billing',
+};
+
+export const shrSummaryDashboardMeta = {
+  slot: 'patient-chart-shr-summary-dashboard-slot',
+  columns: 1,
+  title: 'SHR Summary',
+  path: 'SHR Summary',
+};
+export const benefitsPackageDashboardMeta = {
+  slot: 'patient-chart-benefits-dashboard-slot',
+  columns: 2,
+  title: 'Insurance benefits',
+  path: 'insurance-benefits',
+};
+
+export const accountingDashboardMeta = {
+  name: 'accounting',
+  title: 'Accounting',
+  path: 'accounting',
+};

package/src/declarations.d.ts

@@ -0,0 +1,2 @@
+declare module '*.css';
+declare module '*.scss';

package/src/helpers/README.md

@@ -0,0 +1,174 @@
+# Currency Localization
+
+This module provides locale-based currency formatting for the billing application. It automatically detects the user's locale and formats currency amounts accordingly.
+
+## Features
+
+- **Locale-based currency mapping**: Automatically maps locales to appropriate currencies
+- **Configurable currency mapping**: Supports custom currency mappings via configuration
+- **Consistent formatting**: Provides standardized currency formatting across the application
+- **Fallback support**: Gracefully handles unknown locales with sensible defaults
+
+## Supported Locales and Currencies
+
+| Locale | Currency | Description |
+|--------|----------|-------------|
+| `en` | KES | English - Kenyan Shilling |
+| `sw` | KES | Swahili - Kenyan Shilling |
+| `am` | ETB | Amharic - Ethiopian Birr |
+| `en-KE` | KES | English Kenya |
+| `sw-KE` | KES | Swahili Kenya |
+| `am-ET` | ETB | Amharic Ethiopia |
+
+## Usage
+
+### Basic Currency Formatting
+
+```typescript
+import { formatCurrency, formatCurrencySimple } from './helpers/currency';
+
+// Format with negative sign handling
+const amount = formatCurrency(1234.56); // Returns: "KSh 1,234.56"
+
+// Format without negative sign handling
+const simpleAmount = formatCurrencySimple(1234.56); // Returns: "KSh 1,234.56"
+```
+
+### Using the Hook (with config support)
+
+```typescript
+import { useCurrencyFormatting } from './helpers/currency';
+
+const MyComponent = () => {
+  const { format, formatSimple, getCurrency, getLocale } = useCurrencyFormatting();
+  
+  const amount = format(1234.56);
+  const currency = getCurrency(); // Returns current currency code
+  
+  return <div>Amount: {amount}</div>;
+};
+```
+
+### Direct Currency/Locale Access
+
+```typescript
+import { getCurrencyForLocale, getCurrentLocale } from './helpers/currency';
+
+const currency = getCurrencyForLocale(); // Returns: "KES", "ETB", etc.
+const locale = getCurrentLocale(); // Returns: "en", "sw", "am", etc.
+```
+
+## Configuration
+
+You can customize the locale-to-currency mapping by adding a `localeCurrencyMapping` configuration to your billing config:
+
+```json
+{
+  "localeCurrencyMapping": {
+    "en": "USD",
+    "sw": "KES", 
+    "am": "ETB",
+    "fr": "EUR"
+  }
+}
+```
+
+## Functions
+
+### `formatCurrency(amount, options?)`
+Formats a number as currency with negative sign handling.
+
+**Parameters:**
+- `amount` (number): The amount to format
+- `options` (Intl.NumberFormatOptions, optional): Additional formatting options
+
+**Returns:** Formatted currency string
+
+### `formatCurrencySimple(amount, options?)`
+Formats a number as currency without negative sign handling.
+
+**Parameters:**
+- `amount` (number): The amount to format
+- `options` (Intl.NumberFormatOptions, optional): Additional formatting options
+
+**Returns:** Formatted currency string
+
+### `getCurrencyForLocale()`
+Gets the currency code for the current locale.
+
+**Returns:** Currency code string (e.g., "KES", "ETB")
+
+### `getCurrentLocale()`
+Gets the current locale from localStorage.
+
+**Returns:** Locale string (e.g., "en", "sw", "am")
+
+### `useCurrencyFormatting()`
+React hook that provides currency formatting with config support.
+
+**Returns:** Object with formatting functions and utilities
+
+## Migration from Hardcoded Currency
+
+If you have existing code using hardcoded currency formatting, replace it with the new utilities:
+
+**Before:**
+```typescript
+const formatter = new Intl.NumberFormat('en-US', {
+  style: 'currency',
+  currency: 'KES',
+}).format(amount);
+```
+
+**After:**
+```typescript
+import { formatCurrency } from './helpers/currency';
+
+const formattedAmount = formatCurrency(amount);
+```
+
+## Testing
+
+Run the currency utility tests:
+
+```bash
+npm test -- currency.test.ts
+```
+
+## Examples
+
+### In Components
+
+```typescript
+import React from 'react';
+import { formatCurrency } from './helpers/currency';
+
+const BillItem = ({ price, quantity }) => {
+  const total = price * quantity;
+  
+  return (
+    <div>
+      <span>Price: {formatCurrency(price)}</span>
+      <span>Total: {formatCurrency(total)}</span>
+    </div>
+  );
+};
+```
+
+### In Utilities
+
+```typescript
+import { formatCurrencySimple } from './helpers/currency';
+
+export const createReceipt = (items) => {
+  const total = items.reduce((sum, item) => sum + item.price, 0);
+  
+  return {
+    items: items.map(item => ({
+      ...item,
+      formattedPrice: formatCurrencySimple(item.price)
+    })),
+    total: formatCurrency(total)
+  };
+};
+``` 

package/src/helpers/currency.test.ts

@@ -0,0 +1,114 @@
+import {
+  DEFAULT_LOCALE_CURRENCY_MAP,
+  getCurrencyForLocale,
+  getCurrentLocale,
+  formatCurrency,
+  formatCurrencySimple,
+} from './currency';
+
+// Mock localStorage
+const mockLocalStorage = {
+  getItem: jest.fn(),
+  setItem: jest.fn(),
+  removeItem: jest.fn(),
+  clear: jest.fn(),
+};
+
+Object.defineProperty(window, 'localStorage', {
+  value: mockLocalStorage,
+});
+
+describe('Currency Utilities', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('DEFAULT_LOCALE_CURRENCY_MAP', () => {
+    it('should have correct currency mappings', () => {
+      expect(DEFAULT_LOCALE_CURRENCY_MAP.en).toBe('KES');
+      expect(DEFAULT_LOCALE_CURRENCY_MAP.sw).toBe('KES');
+      expect(DEFAULT_LOCALE_CURRENCY_MAP.am).toBe('ETB');
+      expect(DEFAULT_LOCALE_CURRENCY_MAP['en-KE']).toBe('KES');
+      expect(DEFAULT_LOCALE_CURRENCY_MAP['sw-KE']).toBe('KES');
+      expect(DEFAULT_LOCALE_CURRENCY_MAP['am-ET']).toBe('ETB');
+    });
+  });
+
+  describe('getCurrentLocale', () => {
+    it('should return locale from localStorage', () => {
+      mockLocalStorage.getItem.mockReturnValue('sw');
+      expect(getCurrentLocale()).toBe('sw');
+    });
+
+    it('should return default locale when localStorage is empty', () => {
+      mockLocalStorage.getItem.mockReturnValue(null);
+      expect(getCurrentLocale()).toBe('en');
+    });
+  });
+
+  describe('getCurrencyForLocale', () => {
+    it('should return correct currency for English locale', () => {
+      mockLocalStorage.getItem.mockReturnValue('en');
+      expect(getCurrencyForLocale()).toBe('KES');
+    });
+
+    it('should return correct currency for Swahili locale', () => {
+      mockLocalStorage.getItem.mockReturnValue('sw');
+      expect(getCurrencyForLocale()).toBe('KES');
+    });
+
+    it('should return correct currency for Amharic locale', () => {
+      mockLocalStorage.getItem.mockReturnValue('am');
+      expect(getCurrencyForLocale()).toBe('ETB');
+    });
+
+    it('should return KES as fallback for unknown locale', () => {
+      mockLocalStorage.getItem.mockReturnValue('fr');
+      expect(getCurrencyForLocale()).toBe('KES');
+    });
+  });
+
+  describe('formatCurrency', () => {
+    beforeEach(() => {
+      // Mock Intl.NumberFormat
+      const mockFormatter = {
+        format: jest.fn((value) => `$${value.toFixed(2)}`),
+      };
+      jest.spyOn(Intl, 'NumberFormat').mockImplementation(() => mockFormatter as any);
+    });
+
+    it('should format positive amounts correctly', () => {
+      mockLocalStorage.getItem.mockReturnValue('en');
+      const result = formatCurrency(1234.56);
+      expect(result).toBe('$1234.56');
+    });
+
+    it('should format negative amounts with minus sign', () => {
+      mockLocalStorage.getItem.mockReturnValue('en');
+      const result = formatCurrency(-1234.56);
+      expect(result).toBe('- $1234.56');
+    });
+  });
+
+  describe('formatCurrencySimple', () => {
+    beforeEach(() => {
+      // Mock Intl.NumberFormat
+      const mockFormatter = {
+        format: jest.fn((value) => `$${value.toFixed(2)}`),
+      };
+      jest.spyOn(Intl, 'NumberFormat').mockImplementation(() => mockFormatter as any);
+    });
+
+    it('should format amounts without negative sign handling', () => {
+      mockLocalStorage.getItem.mockReturnValue('en');
+      const result = formatCurrencySimple(1234.56);
+      expect(result).toBe('$1234.56');
+    });
+
+    it('should format negative amounts without special handling', () => {
+      mockLocalStorage.getItem.mockReturnValue('en');
+      const result = formatCurrencySimple(-1234.56);
+      expect(result).toBe('$-1234.56');
+    });
+  });
+});