@digihmis/esm-billing-app 1.0.0

package/src/billing-dashboard/billing-dashboard.resource.ts

@@ -0,0 +1,101 @@
+import { openmrsFetch, restBaseUrl, useSession } from '@openmrs/esm-framework';
+import useSWR from 'swr';
+import { CashPoint, Timesheet } from './type';
+
+/**
+ * Hook to get the current cashier's active timesheet (clocked-in session)
+ */
+export const useCurrentTimesheet = () => {
+  const session = useSession();
+  const providerUuid = session?.currentProvider?.uuid;
+
+  const { data, error, isLoading, mutate } = useSWR<{ data: { results: Array<Timesheet> } }>(
+    providerUuid ? `${restBaseUrl}/cashier/timesheet?cashier=${providerUuid}&getProviderOpenTimesheet=true` : null,
+    openmrsFetch,
+  );
+
+  const activeTimesheet = data?.data?.results?.[0] || null;
+  const isClockedIn = activeTimesheet !== null && activeTimesheet.clockOut === null;
+
+  return {
+    activeTimesheet,
+    isClockedIn,
+    isLoading,
+    error,
+    mutate,
+  };
+};
+
+/**
+ * Get all timesheets for a cashier within a date range
+ */
+export const useTimesheets = (
+  cashierUuid?: string,
+  cashPointUuid?: string,
+  startDatetime?: Date,
+  endDatetime?: Date,
+) => {
+  const params = new URLSearchParams();
+
+  if (cashierUuid) {
+    params.append('cashier', cashierUuid);
+  }
+  if (cashPointUuid) {
+    params.append('cashPoint', cashPointUuid);
+  }
+  if (startDatetime) {
+    params.append('startDatetime', startDatetime.toISOString());
+  }
+  if (endDatetime) {
+    params.append('endDatetime', endDatetime.toISOString());
+  }
+
+  const url = `${restBaseUrl}/cashier/timesheet?${params.toString()}`;
+
+  const { data, error, isLoading, mutate } = useSWR<{ data: { results: Array<Timesheet> } }>(
+    cashierUuid || cashPointUuid || startDatetime || endDatetime ? url : null,
+    openmrsFetch,
+  );
+
+  return {
+    timesheets: data?.data?.results || [],
+    error,
+    isLoading,
+    mutate,
+  };
+};
+
+/**
+ * Hook to fetch all available cash points
+ */
+export const useCashPoints = () => {
+  const url = `${restBaseUrl}/cashier/cashPoint?v=default`;
+
+  const { data, error, isLoading, mutate } = useSWR<{ data: { results: Array<CashPoint> } }>(url, openmrsFetch);
+
+  // Filter out retired cash points
+  const activeCashPoints = data?.data?.results?.filter((cp) => !cp.retired) || [];
+
+  return {
+    cashPoints: activeCashPoints,
+    error,
+    isLoading,
+    mutate,
+  };
+};
+
+/**
+ * Get a specific cash point by UUID
+ */
+export const useCashPoint = (cashPointUuid: string) => {
+  const url = cashPointUuid ? `${restBaseUrl}/cashier/cashPoint/${cashPointUuid}?v=default` : null;
+
+  const { data, error, isLoading, mutate } = useSWR<{ data: CashPoint }>(url, openmrsFetch);
+
+  return {
+    cashPoint: data?.data || null,
+    error,
+    isLoading,
+    mutate,
+  };
+};

package/src/billing-dashboard/billing-dashboard.scss

@@ -0,0 +1,166 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+@use '@carbon/colors';
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+.tileContainer {
+  border: 1px solid colors.$cool-gray-30;
+  margin-bottom: layout.$spacing-04;
+  display: grid;
+  grid-template-columns: 1fr 1fr 1fr 1fr;
+  gap: 0;
+  height: 80px;
+
+  :global(.omrs-breakpoint-lt-desktop) & {
+    padding: layout.$spacing-04;
+  }
+
+  :global(.omrs-breakpoint-lt-tablet) & {
+    padding: layout.$spacing-03;
+    grid-template-columns: 1fr;
+    grid-template-rows: auto auto auto;
+    gap: layout.$spacing-04;
+  }
+}
+
+.tileHeader {
+  color: colors.$gray-70;
+  margin-bottom: layout.$spacing-03;
+  text-transform: none;
+  letter-spacing: 0;
+
+  :global(.omrs-breakpoint-lt-tablet) & {
+    margin-bottom: layout.$spacing-02;
+  }
+}
+
+.displayDetails {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+
+  :global(.omrs-breakpoint-lt-tablet) & {
+    padding: layout.$spacing-03 0;
+    border-right: none;
+    border-bottom: 1px solid colors.$gray-20;
+    padding-bottom: layout.$spacing-04;
+    margin-bottom: layout.$spacing-03;
+  }
+}
+
+.countLabel {
+  color: colors.$gray-70;
+  margin-bottom: layout.$spacing-02;
+  @include type.type-style('caption-01');
+  font-weight: bold;
+
+  :global(.omrs-breakpoint-lt-tablet) & {
+    @include type.type-style('caption-01');
+    font-weight: bold;
+    margin-bottom: layout.$spacing-01;
+  }
+}
+
+.displayData {
+  color: colors.$gray-100;
+  font-weight: bold;
+  @include type.type-style('caption-01');
+  font-size: 25px;
+
+  :global(.omrs-breakpoint-lt-tablet) & {
+    font-size: 2.625rem;
+    line-height: 2.75rem;
+  }
+}
+
+.headerActions {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding-right: 1rem;
+
+  :global(.omrs-breakpoint-lt-tablet) & {
+    gap: 0.25rem;
+  }
+}
+
+.dashboardContainer {
+  padding: layout.$spacing-05;
+  padding-bottom: 0;
+  background-color: var(--cds-field);
+
+  :global(.omrs-breakpoint-lt-desktop) & {
+    padding: layout.$spacing-02;
+    padding-bottom: 0;
+  }
+
+  :global(.omrs-breakpoint-lt-tablet) & {
+    padding: layout.$spacing-03;
+    padding-bottom: 0;
+  }
+}
+
+.clockInInfo {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  width: 100%;
+  gap: layout.$spacing-03;
+
+  :global(.omrs-breakpoint-lt-tablet) & {
+    flex-direction: row;
+    align-items: center;
+    gap: layout.$spacing-02;
+  }
+}
+
+.clockInText {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 0.25rem;
+
+  :global(.omrs-breakpoint-lt-tablet) & {
+    font-size: 0.875rem;
+  }
+}
+
+.clockInTime {
+  color: colors.$gray-70;
+  white-space: nowrap;
+}
+
+.alarmIcon {
+  flex-shrink: 0;
+
+  :global(.omrs-breakpoint-lt-tablet) & {
+    width: 18px;
+    height: 18px;
+  }
+}
+
+.emptyStateContainer {
+  border: 1px solid colors.$gray-20;
+  padding: 3rem 0;
+}
+
+.tile {
+  margin: auto;
+  width: fit-content;
+  background: colors.$gray-20;
+}
+
+.tileContent {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+}
+
+.content {
+  @include type.type-style('heading-compact-02');
+  color: colors.$gray-70;
+  margin-bottom: layout.$spacing-03;
+}
+.loader {
+  min-height: fit-content;
+}

package/src/billing-dashboard/metrics/metrics.resource.ts

@@ -0,0 +1,142 @@
+import dayjs from 'dayjs';
+import { type MappedBill, type PatientInvoice, PaymentStatus } from '../type';
+import { formatDate, openmrsFetch, parseDate, restBaseUrl } from '@openmrs/esm-framework';
+import sortBy from 'lodash-es/sortBy';
+import useSWR from 'swr';
+import isEmpty from 'lodash-es/isEmpty';
+import { extractString, useCurrencyFormatting } from '../../utils';
+
+export const mapBillProperties = (bill: PatientInvoice): MappedBill => {
+  const mappedBill: MappedBill = {
+    id: bill?.id,
+    uuid: bill?.uuid,
+    patientName: bill?.patient?.display.split('-')?.[1],
+    identifier: bill?.patient?.display.split('-')?.[0],
+    patientUuid: bill?.patient?.uuid,
+    status: bill?.lineItems.some((item) => item?.paymentStatus === PaymentStatus.PENDING)
+      ? PaymentStatus.PENDING
+      : PaymentStatus.PAID,
+    receiptNumber: bill?.receiptNumber,
+    cashier: bill?.cashier,
+    cashPointUuid: bill?.cashPoint?.uuid,
+    cashPointName: bill?.cashPoint?.name,
+    cashPointLocation: bill?.cashPoint?.location?.display,
+    dateCreated: bill?.dateCreated ? formatDate(parseDate(bill?.dateCreated), { mode: 'wide' }) : '--',
+    dateCreatedUnformatted: bill?.dateCreated,
+    lineItems: bill?.lineItems.filter((li) => !li?.voided),
+    billingService: extractString(
+      bill?.lineItems.map((bill) => bill?.item || bill?.billableService || '--').join('  '),
+    ),
+    payments: bill?.payments,
+    display: bill?.display,
+    totalAmount: bill?.lineItems?.map((item) => item?.price * item?.quantity).reduce((prev, curr) => prev + curr, 0),
+    tenderedAmount: bill?.payments?.map((item) => item?.amountTendered).reduce((prev, curr) => prev + curr, 0),
+    referenceCodes: bill?.payments
+      .map((payment) =>
+        payment.attributes
+          .filter((attr) => attr.attributeType.description === 'Reference Number')
+          .map((attr) => {
+            return {
+              paymentMode: payment.instanceType.name,
+              value: attr.value,
+            };
+          }),
+      )
+      .flat()
+      .map((ref) => `${ref.paymentMode}: ${ref.value}`)
+      .join(', '),
+    adjustmentReason: bill?.adjustmentReason,
+    balance: bill?.balance,
+    totalPayments: bill?.totalPayments,
+    totalDeposits: bill?.totalDeposits,
+    totalExempted: bill?.totalExempted,
+    closed: bill?.closed,
+  };
+
+  return mappedBill;
+};
+export const useBills = (
+  patientUuid: string = '',
+  billStatus: PaymentStatus.PENDING | '' | string = '',
+  startingDate: Date = dayjs().startOf('day').toDate(),
+  endDate: Date = dayjs().endOf('day').toDate(),
+) => {
+  const startingDateISO = startingDate.toISOString();
+  const endDateISO = endDate.toISOString();
+
+  const url = `${restBaseUrl}/cashier/bill?status=${billStatus}&v=custom:(uuid,display,voided,voidReason,adjustedBy,cashPoint:(uuid,name),cashier:(uuid,display),dateCreated,lineItems,patient:(uuid,display))&createdOnOrAfter=${startingDateISO}&createdOnOrBefore=${endDateISO}`;
+
+  const { data, error, isLoading, isValidating, mutate } = useSWR<{ data: { results: Array<PatientInvoice> } }>(
+    patientUuid ? `${url}&patientUuid=${patientUuid}` : url,
+    openmrsFetch,
+    {
+      errorRetryCount: 2,
+    },
+  );
+
+  const sortBills = sortBy(data?.data?.results ?? [], ['dateCreated']).reverse();
+  const filteredBills = billStatus === '' ? sortBills : sortBills?.filter((bill) => bill?.status === billStatus);
+  const mappedResults = filteredBills?.map((bill) => mapBillProperties(bill));
+  const filteredResults = mappedResults?.filter((res) => res.patientUuid === patientUuid);
+  const formattedBills = isEmpty(patientUuid) ? mappedResults : filteredResults || [];
+
+  return {
+    bills: formattedBills,
+    error,
+    isLoading,
+    isValidating,
+    mutate,
+  };
+};
+
+/**
+ * A custom hook for calculating bill metrics.
+ *
+ * This hook takes in an array of bills and calculates the total amount for different
+ * bill statuses (cumulative, pending, paid) using provided helper functions.
+ *
+ * @param {Array<Object>} bills - An array of bill objects. Each bill object should have a `status` and `lineItems` properties.
+ *
+ */
+
+export const useBillMetrics = (
+  bills: Array<MappedBill>,
+): {
+  totalBills: string;
+  pendingBills: string;
+  paidBills: string;
+  exemptedBills: string;
+} => {
+  const { paidTotal, pendingTotal, cumulativeTotal, exemptedTotal } = calculateBillTotals(bills);
+  const { format: formatCurrency } = useCurrencyFormatting();
+
+  return {
+    totalBills: formatCurrency(cumulativeTotal),
+    pendingBills: formatCurrency(pendingTotal),
+    paidBills: formatCurrency(paidTotal),
+    exemptedBills: formatCurrency(exemptedTotal),
+  };
+};
+
+const calculateBillTotals = (bills: Array<MappedBill>) => {
+  let paidTotal = 0;
+  let pendingTotal = 0;
+  let cumulativeTotal = 0;
+  let exemptedTotal = 0;
+
+  bills.forEach((bill) => {
+    const amount = bill.totalAmount || 0;
+    if (bill.status === PaymentStatus.PAID) {
+      paidTotal += amount;
+    } else if (bill.status === PaymentStatus.PENDING) {
+      pendingTotal += amount;
+    } else if (bill.status === PaymentStatus.EXEMPTED) {
+      exemptedTotal += amount;
+    }
+    cumulativeTotal += amount;
+  });
+
+  return { paidTotal, pendingTotal, cumulativeTotal, exemptedTotal };
+};
+
+export default calculateBillTotals;

package/src/billing-dashboard/type/index.ts

@@ -0,0 +1,176 @@
+import { OpenmrsResource } from '@openmrs/esm-framework/';
+
+export enum PaymentStatus {
+  POSTED = 'POSTED',
+  PENDING = 'PENDING',
+  PAID = 'PAID',
+  CREDITED = 'CREDITED',
+  CANCELLED = 'CANCELLED',
+  ADJUSTED = 'ADJUSTED',
+  EXEMPTED = 'EXEMPTED',
+}
+export interface Provider {
+  uuid: string;
+  display: string;
+}
+
+export interface LineItem {
+  uuid: string;
+  display: string;
+  voided: boolean;
+  voidReason: string | null;
+  item: string;
+  billableService: string;
+  quantity: number;
+  price: number;
+  priceName: string;
+  priceUuid: string;
+  lineItemOrder: number;
+  resourceVersion: string;
+  paymentStatus: string;
+  itemOrServiceConceptUuid: string;
+  serviceTypeUuid: string;
+  order: OpenmrsResource;
+}
+interface AttributeType {
+  uuid?: string;
+  name: string;
+  description: string;
+  retired: boolean;
+  attributeOrder?: number;
+  format?: string;
+  foreignKey?: string | null;
+  regExp?: string | null;
+  required: boolean;
+  value?: string;
+}
+
+interface Attribute {
+  uuid: string;
+  display: string;
+  voided: boolean;
+  voidReason: string | null;
+  value: string;
+  attributeType: AttributeType;
+  order: number;
+  valueName: string;
+  resourceVersion: string;
+}
+interface PaymentInstanceType {
+  uuid: string;
+  name: string;
+  description: string;
+  retired: boolean;
+}
+export interface Payment {
+  uuid: string;
+  instanceType: PaymentInstanceType;
+  attributes: Array<Attribute>;
+  amount: number;
+  amountTendered: number;
+  dateCreated: number;
+  voided: boolean;
+  resourceVersion: string;
+}
+export interface MappedBill {
+  uuid: string;
+  id: number;
+  patientUuid: string;
+  patientName: string;
+  cashPointUuid: string;
+  cashPointName: string;
+  cashPointLocation: string;
+  cashier: Provider;
+  receiptNumber: string;
+  status: PaymentStatus;
+  identifier: string;
+  dateCreated: string;
+  dateCreatedUnformatted: string;
+  lineItems: Array<LineItem>;
+  billingService: string;
+  payments: Array<Payment>;
+  totalAmount?: number;
+  tenderedAmount?: number;
+  display?: string;
+  referenceCodes?: string;
+  adjustmentReason?: string;
+  totalPayments?: number;
+  totalDeposits?: number;
+  totalExempted?: number;
+  balance?: number;
+  closed?: boolean;
+}
+interface LocationLink {
+  rel: string;
+  uri: string;
+  resourceAlias: string;
+}
+
+interface Location {
+  uuid: string;
+  display: string;
+  links: Array<LocationLink>;
+}
+export interface CashPoint {
+  uuid: string;
+  name: string;
+  description: string;
+  retired: boolean;
+  location: Location;
+}
+
+interface PatientLink {
+  rel: string;
+  uri: string;
+  resourceAlias: string;
+}
+
+export interface Patient {
+  uuid: string;
+  display: string;
+  links: Array<PatientLink>;
+  identifiers: Array<{ uuid: string; display: string }>;
+}
+export interface PatientInvoice {
+  uuid: string;
+  display: string;
+  voided: boolean;
+  voidReason: string | null;
+  adjustedBy: any[];
+  billAdjusted: any;
+  cashPoint: CashPoint;
+  cashier: Provider;
+  dateCreated: string;
+  lineItems: Array<LineItem>;
+  patient: Patient;
+  payments: Payment[];
+  receiptNumber: string;
+  status: PaymentStatus;
+  adjustmentReason: any;
+  id: number;
+  resourceVersion: string;
+  totalPayments?: number;
+  totalDeposits?: number;
+  totalExempted?: number;
+  balance?: number;
+  closed?: boolean;
+}
+
+export interface Timesheet {
+  uuid: string;
+  cashier: {
+    uuid: string;
+    display: string;
+  };
+  cashPoint: {
+    uuid: string;
+    name: string;
+    location?: {
+      uuid: string;
+      display: string;
+    };
+  };
+  clockIn: string;
+  clockOut: string | null;
+  display: string;
+}

package/src/billing-header/page-header/page-header.component.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import { Calendar } from '@carbon/react/icons';
+import { useSession, formatDate, ExtensionSlot, useConfig } from '@openmrs/esm-framework';
+import styles from './page-header.scss';
+import { IconWrapper } from './page-icon/icon-wrapper.extension';
+import { BillingConfig } from '../../config-schema';
+
+export const PageHeader: React.FC = () => {
+  const { t } = useTranslation();
+  const userSession = useSession();
+  const { billingIcon } = useConfig<BillingConfig>();
+  const userLocation = userSession?.sessionLocation?.display;
+
+  return (
+    <div className={styles.header}>
+      <div className={styles['left-justified-items']}>
+        <IconWrapper src={billingIcon.src} alt={billingIcon.alt} />
+        <div className={styles['page-labels']}>
+          <p className={styles['page-name']}>{userLocation}</p>
+          <p className={styles['page-subtitle']}>{t('billingHeader', 'Billing')}</p>
+        </div>
+      </div>
+      <div className={styles['right-justified-items']}>
+        <div className={styles.extensionSlot}>
+          <ExtensionSlot name={'provider-banner-slot'} />
+          <div className={styles['date-and-location']}>
+            <Calendar size={16} />
+            <span className={styles.value}>{formatDate(new Date(), { mode: 'wide', noToday: true })}</span>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+};

package/src/billing-header/page-header/page-header.scss

@@ -0,0 +1,76 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+@use '@carbon/colors';
+
+.header {
+  @include type.type-style('body-compact-02');
+  height: layout.$spacing-12;
+  border: 1px solid colors.$gray-20;
+  border-left: 0px;
+  display: flex;
+  background: var(--cds-field);
+  justify-content: space-between;
+  margin-top: 1.5rem;
+}
+
+.left-justified-items {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+}
+
+.right-justified-items {
+  @include type.type-style('body-01');
+  color: colors.$gray-80;
+  padding-top: layout.$spacing-05;
+  padding-bottom: layout.$spacing-07;
+}
+
+.page-subtitle {
+  @include type.type-style('caption-01');
+  color: colors.$gray-70;
+  font-size: layout.$spacing-06;
+}
+.page-name {
+  @include type.type-style('caption-01');
+  color: colors.$gray-80;
+  font-size: layout.$spacing-05;
+}
+
+.page-labels {
+  p:first-of-type {
+    margin-bottom: layout.$spacing-02;
+  }
+}
+
+.date-and-location {
+  margin-top: layout.$spacing-03;
+  display: flex;
+  justify-content: flex-end;
+  align-items: center;
+  margin-right: layout.$spacing-05;
+  @include type.type-style('caption-01');
+  font-size: 0.83rem;
+}
+
+.value {
+  margin-left: layout.$spacing-02;
+}
+
+.middot {
+  margin: 0 layout.$spacing-03;
+}
+
+.view {
+  @include type.type-style('caption-01');
+}
+
+svg.iconOverrides {
+  width: 72 !important;
+  height: 72 !important;
+}
+
+.svgContainer svg {
+  width: 72px;
+  height: 72px;
+}

package/src/billing-header/page-header/page-icon/icon-wrapper.extension.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+
+interface IconWrapperProps {
+  src: string;
+  alt?: string;
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+export const IconWrapper: React.FC<IconWrapperProps> = ({
+  src,
+  alt = 'Icon',
+  className,
+  style = { width: '100px', height: '148px' },
+}) => {
+  return <img src={src} alt={alt} className={className} style={style} />;
+};