@kenyaemr/esm-etims-app 5.4.5-pre.1109

package/src/global-properties/etims-global-properties-form.workspace.tsx

@@ -0,0 +1,244 @@
+import React, { useEffect, useMemo, useState } from 'react';
+import {
+  Button,
+  ButtonSet,
+  Form,
+  InlineLoading,
+  PasswordInput,
+  Select,
+  SelectItem,
+  Stack,
+  TextInput,
+  Toggle,
+} from '@carbon/react';
+import {
+  ErrorState,
+  showSnackbar,
+  useLayoutType,
+  Workspace2,
+  type Workspace2DefinitionProps,
+} from '@openmrs/esm-framework';
+import classNames from 'classnames';
+import { useTranslation } from 'react-i18next';
+import {
+  saveEtimsGlobalProperty,
+  etimsPropertyKeys,
+  useEtimsGlobalProperties,
+  type EtimsPropertyName,
+  type EtimsGlobalProperty,
+} from './etims-global-properties.resource';
+import styles from './etims-global-properties-form.workspace.scss';
+
+type FormValues = Record<EtimsPropertyName, string>;
+
+const emptyValues = Object.fromEntries(Object.keys(etimsPropertyKeys).map((key) => [key, ''])) as FormValues;
+
+const propertiesToValues = (properties: EtimsGlobalProperty[]): FormValues => {
+  const values = { ...emptyValues };
+  Object.entries(etimsPropertyKeys).forEach(([name, property]) => {
+    values[name as EtimsPropertyName] = properties.find((candidate) => candidate.property === property)?.value ?? '';
+  });
+  return values;
+};
+
+type EtimsGlobalPropertiesWorkspaceProps = {
+  mutateProperties?: () => void;
+};
+
+const EtimsGlobalPropertiesFormWorkspace: React.FC<
+  Workspace2DefinitionProps<EtimsGlobalPropertiesWorkspaceProps, {}, {}>
+> = ({ closeWorkspace, workspaceProps }) => {
+  const { t } = useTranslation();
+  const isTablet = useLayoutType() === 'tablet';
+  const { properties, error, isLoading, mutate } = useEtimsGlobalProperties();
+  const [values, setValues] = useState<FormValues>(emptyValues);
+  const [savedValues, setSavedValues] = useState<FormValues>(emptyValues);
+  const [isSaving, setIsSaving] = useState(false);
+
+  useEffect(() => {
+    if (!isLoading) {
+      const nextValues = propertiesToValues(properties);
+      setValues(nextValues);
+      setSavedValues(nextValues);
+    }
+  }, [isLoading, properties]);
+
+  const isDirty = useMemo(() => JSON.stringify(values) !== JSON.stringify(savedValues), [savedValues, values]);
+  const updateValue = (name: EtimsPropertyName, value: string) =>
+    setValues((current) => ({ ...current, [name]: value }));
+
+  const handleSubmit = async (event: React.FormEvent) => {
+    event.preventDefault();
+    setIsSaving(true);
+    try {
+      const changedProperties = Object.entries(etimsPropertyKeys).filter(([name, property]) => {
+        const exists = properties.some((candidate) => candidate.property === property);
+        return !exists || values[name as EtimsPropertyName] !== savedValues[name as EtimsPropertyName];
+      });
+      await Promise.all(
+        changedProperties.map(([name, property]) =>
+          saveEtimsGlobalProperty(
+            property,
+            values[name as EtimsPropertyName],
+            properties.find((candidate) => candidate.property === property)?.uuid,
+          ),
+        ),
+      );
+      await mutate();
+      workspaceProps?.mutateProperties?.();
+      setSavedValues(values);
+      showSnackbar({
+        kind: 'success',
+        title: t('etimsConfigurationSaved', 'eTIMS configuration saved'),
+        subtitle: t('etimsConfigurationSavedMessage', 'The eTIMS global properties were updated successfully.'),
+      });
+      closeWorkspace({ discardUnsavedChanges: true });
+    } catch (saveError: any) {
+      showSnackbar({
+        kind: 'error',
+        title: t('errorSavingEtimsConfiguration', 'Error saving eTIMS configuration'),
+        subtitle: saveError?.message,
+      });
+    } finally {
+      setIsSaving(false);
+    }
+  };
+
+  const textField = (name: EtimsPropertyName, label: string, helperText?: string, type?: 'number') => (
+    <TextInput
+      id={`etims-${name}`}
+      labelText={label}
+      helperText={helperText}
+      type={type ?? 'text'}
+      min={type === 'number' ? 0 : undefined}
+      value={values[name]}
+      onChange={(event) => updateValue(name, event.target.value)}
+    />
+  );
+
+  return (
+    <Workspace2
+      title={t('configureEtimsGlobalProperties', 'Configure eTIMS global properties')}
+      hasUnsavedChanges={isDirty}>
+      {isLoading ? (
+        <InlineLoading description={t('loadingEtimsConfiguration', 'Loading eTIMS configuration...')} />
+      ) : error ? (
+        <ErrorState error={error} headerTitle={t('etimsGlobalProperties', 'eTIMS global properties')} />
+      ) : (
+        <Form className={styles.form} onSubmit={handleSubmit}>
+          <div className={styles.formContainer}>
+            <Stack gap={5}>
+              <p className={styles.intro}>
+                {t(
+                  'etimsGlobalPropertiesDescription',
+                  'Configure the connection, resilience, invoicing, and integration settings used by eTIMS.',
+                )}
+              </p>
+              <section className={styles.section}>
+                <h2 className={styles.sectionTitle}>{t('connectionAndCredentials', 'Connection and credentials')}</h2>
+                <div className={styles.fields}>
+                  <div className={styles.fullWidth}>
+                    <Toggle
+                      id="etims-enabled"
+                      labelText={t('etimsEnabled', 'eTIMS enabled')}
+                      labelA={t('no', 'No')}
+                      labelB={t('yes', 'Yes')}
+                      toggled={values.enabled === 'true'}
+                      onToggle={(enabled) => updateValue('enabled', String(enabled))}
+                    />
+                  </div>
+                  <Select
+                    id="etims-environment"
+                    labelText={t('environment', 'Environment')}
+                    value={values.environment}
+                    onChange={(event) => updateValue('environment', event.target.value)}>
+                    <SelectItem value="" text={t('selectEnvironment', 'Select an environment')} />
+                    <SelectItem value="sandbox" text={t('sandbox', 'Sandbox')} />
+                    <SelectItem value="production" text={t('production', 'Production')} />
+                  </Select>
+                  {textField('baseUrl', t('baseUrl', 'Base URL'))}
+                  {textField('businessPin', t('businessPin', 'Business PIN'))}
+                  {textField('branchId', t('branchId', 'Branch ID'))}
+                  <PasswordInput
+                    id="etims-apiKey"
+                    labelText={t('apiKey', 'API key')}
+                    value={values.apiKey}
+                    onChange={(event) => updateValue('apiKey', event.target.value)}
+                  />
+                  {textField(
+                    'sandboxValidatedContractVersion',
+                    t('sandboxValidatedContractVersion', 'Sandbox validated contract version'),
+                  )}
+                </div>
+              </section>
+              <section className={styles.section}>
+                <h2 className={styles.sectionTitle}>{t('timeoutsAndRetries', 'Timeouts and retries')}</h2>
+                <div className={styles.fields}>
+                  {textField(
+                    'connectTimeout',
+                    t('connectTimeout', 'Connect timeout'),
+                    t('milliseconds', 'Milliseconds'),
+                    'number',
+                  )}
+                  {textField(
+                    'readTimeout',
+                    t('readTimeout', 'Read timeout'),
+                    t('milliseconds', 'Milliseconds'),
+                    'number',
+                  )}
+                  {textField('maxAttempts', t('maxAttempts', 'Maximum attempts'), undefined, 'number')}
+                  {textField(
+                    'retryInterval',
+                    t('retryInterval', 'Retry interval'),
+                    t('milliseconds', 'Milliseconds'),
+                    'number',
+                  )}
+                </div>
+              </section>
+              <section className={styles.section}>
+                <h2 className={styles.sectionTitle}>{t('invoiceAndPayment', 'Invoice and payment')}</h2>
+                <div className={styles.fields}>
+                  {textField('invoiceNumberSource', t('invoiceNumberSource', 'Invoice number source'))}
+                  {textField(
+                    'localInvoiceNumberStart',
+                    t('localInvoiceNumberStart', 'Local invoice number start'),
+                    undefined,
+                    'number',
+                  )}
+                  <div className={styles.fullWidth}>
+                    {textField(
+                      'paymentModeMappingFile',
+                      t('paymentModeMappingFile', 'Payment mode mapping file'),
+                      t('paymentModeMappingFileHelp', 'Path to the payment mode mapping configuration file.'),
+                    )}
+                  </div>
+                </div>
+              </section>
+            </Stack>
+          </div>
+          <ButtonSet
+            className={classNames({
+              [styles.tablet]: isTablet,
+              [styles.desktop]: !isTablet,
+            })}>
+            <Button className={styles.buttonContainer} kind="secondary" type="button" onClick={() => closeWorkspace()}>
+              {t('cancel', 'Cancel')}
+            </Button>
+            <Button className={styles.buttonContainer} type="submit" disabled={!isDirty || isSaving}>
+              {isSaving ? (
+                <span className={styles.inlineLoading}>
+                  {t('saving', 'Saving...')}
+                  <InlineLoading status="active" iconDescription="Loading" />
+                </span>
+              ) : (
+                t('save', 'Save')
+              )}
+            </Button>
+          </ButtonSet>
+        </Form>
+      )}
+    </Workspace2>
+  );
+};
+
+export default EtimsGlobalPropertiesFormWorkspace;

package/src/global-properties/etims-global-properties.resource.ts

@@ -0,0 +1,60 @@
+import { type FetchResponse, openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import useSWR from 'swr';
+
+export interface EtimsGlobalProperty {
+  uuid: string;
+  property: string;
+  value: string | null;
+}
+
+interface SystemSettingResponse {
+  results: EtimsGlobalProperty[];
+}
+
+export const ETIMS_PROPERTY_PREFIX = 'kenyaemr.cashier.etims.';
+export const etimsPropertyKeys = {
+  enabled: `${ETIMS_PROPERTY_PREFIX}enabled`,
+  environment: `${ETIMS_PROPERTY_PREFIX}environment`,
+  baseUrl: `${ETIMS_PROPERTY_PREFIX}baseUrl`,
+  businessPin: `${ETIMS_PROPERTY_PREFIX}businessPin`,
+  branchId: `${ETIMS_PROPERTY_PREFIX}branchId`,
+  connectTimeout: `${ETIMS_PROPERTY_PREFIX}connectTimeout`,
+  readTimeout: `${ETIMS_PROPERTY_PREFIX}readTimeout`,
+  maxAttempts: `${ETIMS_PROPERTY_PREFIX}maxAttempts`,
+  retryInterval: `${ETIMS_PROPERTY_PREFIX}retryInterval`,
+  invoiceNumberSource: `${ETIMS_PROPERTY_PREFIX}invoiceNumberSource`,
+  localInvoiceNumberStart: `${ETIMS_PROPERTY_PREFIX}localInvoiceNumberStart`,
+  paymentModeMappingFile: `${ETIMS_PROPERTY_PREFIX}paymentModeMappingFile`,
+  apiKey: `${ETIMS_PROPERTY_PREFIX}apiKey`,
+  sandboxValidatedContractVersion: `${ETIMS_PROPERTY_PREFIX}sandboxValidatedContractVersion`,
+} as const;
+
+export type EtimsPropertyName = keyof typeof etimsPropertyKeys;
+const emptyProperties: EtimsGlobalProperty[] = [];
+
+export const useEtimsGlobalProperties = () => {
+  const url = `${restBaseUrl}/systemsetting?q=${encodeURIComponent(
+    ETIMS_PROPERTY_PREFIX,
+  )}&v=custom:(uuid,property,value)`;
+  const { data, error, isLoading, mutate } = useSWR<FetchResponse<SystemSettingResponse>>(url, openmrsFetch);
+
+  return {
+    properties: data?.data?.results ?? emptyProperties,
+    error,
+    isLoading,
+    mutate,
+  };
+};
+
+export async function saveEtimsGlobalProperty(property: string, value: string, uuid?: string): Promise<void> {
+  const response = await openmrsFetch(uuid ? `${restBaseUrl}/systemsetting/${uuid}` : `${restBaseUrl}/systemsetting`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ property, value }),
+  });
+
+  if (!response.ok) {
+    const responseBody = await response.json().catch(() => ({}));
+    throw new Error(responseBody?.error?.message ?? `Failed to save ${property}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,100 @@
+import { type ComponentType } from 'react';
+import { defineConfigSchema, getAsyncLifecycle, type IconId } from '@openmrs/esm-framework';
+import { configSchema } from './config-schema';
+
+const moduleName = '@kenyaemr/esm-etims-app';
+
+const options = {
+  featureName: 'esm-etims-app',
+  moduleName,
+};
+
+export const importTranslation = require.context('../translations', false, /.json$/, 'lazy');
+
+export const root = getAsyncLifecycle(() => import('./root.component'), options);
+
+const loadEtimsLeftPanelLink =
+  (title: string, name: string, icon: IconId) => (): Promise<{ default: ComponentType<unknown> }> =>
+    import('./left-panel-link.component').then((module) => ({
+      default: module.createLeftPanelLink({
+        title,
+        name,
+        icon,
+      }),
+    }));
+
+// t('status', 'Status')
+export const etimsLeftPanelLink = getAsyncLifecycle(
+  loadEtimsLeftPanelLink('status', '', 'omrs-icon-activity'),
+  options,
+);
+// t('referenceData', 'Reference data')
+export const etimsReferenceDataLeftPanelLink = getAsyncLifecycle(
+  loadEtimsLeftPanelLink('referenceData', 'reference-data', 'omrs-icon-report'),
+  options,
+);
+// t('itemMappings', 'Item mappings')
+export const etimsItemMappingLeftPanelLink = getAsyncLifecycle(
+  loadEtimsLeftPanelLink('itemMappings', 'item-mappings', 'omrs-icon-inventory-management'),
+  options,
+);
+// t('transactions', 'Transactions')
+export const etimsTransactionLeftPanelLink = getAsyncLifecycle(
+  loadEtimsLeftPanelLink('transactions', 'transactions', 'omrs-icon-document'),
+  options,
+);
+// t('creditNotes', 'Credit notes')
+export const etimsCreditNoteLeftPanelLink = getAsyncLifecycle(
+  loadEtimsLeftPanelLink('creditNotes', 'credit-notes', 'omrs-icon-money'),
+  options,
+);
+// t('eTimsConfigs', 'Etims Configs')
+export const etimsGlobalPropertiesLeftPanelLink = getAsyncLifecycle(
+  loadEtimsLeftPanelLink('eTimsConfigs', 'global-properties', 'omrs-icon-settings'),
+  options,
+);
+export const etimsItemMappingForm = getAsyncLifecycle(
+  () => import('./item-mapping/etims-item-mapping-form.workspace'),
+  options,
+);
+export const etimsGlobalPropertiesForm = getAsyncLifecycle(
+  () => import('./global-properties/etims-global-properties-form.workspace'),
+  options,
+);
+export const etimsVoidItemMappingModal = getAsyncLifecycle(
+  () => import('./item-mapping/void-item-mapping.modal'),
+  options,
+);
+export const etimsRegisterItemMappingModal = getAsyncLifecycle(
+  () => import('./item-mapping/register-item-mapping.modal'),
+  options,
+);
+export const etimsTransactionDetails = getAsyncLifecycle(
+  () => import('./transaction/etims-transaction-details.workspace'),
+  options,
+);
+export const etimsCreditNoteForm = getAsyncLifecycle(
+  () => import('./credit-note/etims-credit-note.workspace'),
+  options,
+);
+export const etimsConfirmTransactionActionModal = getAsyncLifecycle(
+  () => import('./transaction/confirm-transaction-action.modal'),
+  options,
+);
+export const etimsOverrideReconciliationModal = getAsyncLifecycle(
+  () => import('./transaction/override-reconciliation.modal'),
+  options,
+);
+export const etimsNavLink = getAsyncLifecycle(
+  () => import('./components/user-menu-link/user-menu-link.component'),
+  options,
+);
+
+export const etimsSyncMetaDataModal = getAsyncLifecycle(
+  () => import('./reference-data/etims-sync-meta.modal'),
+  options,
+);
+
+export function startupApp() {
+  defineConfigSchema(moduleName, configSchema);
+}

package/src/item-mapping/etims-item-mapping-dashboard.component.tsx

@@ -0,0 +1,29 @@
+import React from 'react';
+import { UserHasAccess } from '@openmrs/esm-framework';
+import { useTranslation } from 'react-i18next';
+import Header from '../components/header/header.component';
+import EtimsItemMappingTable from './etims-item-mapping-table.component';
+import styles from './etims-item-mapping-dashboard.scss';
+
+const EtimsItemMappingContent: React.FC = () => {
+  return (
+    <div className={styles.dashboard}>
+      <EtimsItemMappingTable />
+    </div>
+  );
+};
+
+const EtimsItemMappingDashboard: React.FC = () => {
+  const { t } = useTranslation();
+
+  return (
+    <div className={styles.dashboardContainer}>
+      <Header title={t('itemMappings', 'Item mappings')} />
+      <UserHasAccess privilege="Manage eTIMS Configuration">
+        <EtimsItemMappingContent />
+      </UserHasAccess>
+    </div>
+  );
+};
+
+export default EtimsItemMappingDashboard;

package/src/item-mapping/etims-item-mapping-dashboard.scss

@@ -0,0 +1,42 @@
+@use '@carbon/colors';
+@use '@carbon/layout';
+@use '@carbon/type';
+
+.dashboard {
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-05;
+  padding: layout.$spacing-05;
+}
+
+.cardsRow {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: layout.$spacing-05;
+}
+
+.tile {
+  border: 1px solid colors.$gray-20;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: layout.$spacing-03;
+  min-height: layout.$spacing-10;
+}
+
+.tileLabel {
+  @include type.type-style('heading-compact-01');
+  color: colors.$gray-70;
+}
+
+:global(.omrs-breakpoint-lt-desktop) {
+  .cardsRow {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+:global(.omrs-breakpoint-lt-tablet) {
+  .cardsRow {
+    grid-template-columns: 1fr;
+  }
+}

package/src/item-mapping/etims-item-mapping-form.fields.tsx

@@ -0,0 +1,136 @@
+import React, { useMemo } from 'react';
+import { ComboBox, InlineLoading } from '@carbon/react';
+import { ResponsiveWrapper } from '@openmrs/esm-framework';
+import { useTranslation } from 'react-i18next';
+import { formatCodeOption, resolveCodeOption } from './etims-item-mapping.resource';
+import type { CodeOption } from './etims-item-mapping.types';
+import styles from './etims-item-mapping-form.workspace.scss';
+
+/**
+ * Keeps the currently selected item visible in the list even when it is not part of the latest
+ * async search results (e.g. after a debounced query returns a narrower set).
+ */
+const includeSelectedItem = <T,>(items: T[], selected: T | null | undefined, getKey: (item: T) => string) => {
+  if (!selected) {
+    return items;
+  }
+
+  const selectedKey = getKey(selected);
+  if (!selectedKey || items.some((item) => getKey(item) === selectedKey)) {
+    return items;
+  }
+
+  return [selected, ...items];
+};
+
+/**
+ * Carbon's ComboBox echoes the selected item's label back through `onInputChange`. This detects that
+ * echo so it isn't mistaken for a new search term.
+ */
+const isSelectionEcho = <T,>(value: string, items: T[], itemToString: (item?: T | null) => string) =>
+  items.some((item) => itemToString(item) === value);
+
+interface AsyncSearchComboBoxProps<T> {
+  id: string;
+  titleText: string;
+  placeholder: string;
+  items: T[];
+  selectedItem: T | null;
+  itemToString: (item?: T | null) => string;
+  getKey: (item: T) => string;
+  isLoading?: boolean;
+  onSearch: (value: string) => void;
+  onSelect: (item: T | null) => void;
+  invalid?: boolean;
+  invalidText?: string;
+}
+
+/**
+ * A server-side searchable ComboBox that surfaces a loading indicator and preserves the current
+ * selection across searches. Used for billable services, stock items and item classes.
+ */
+export function AsyncSearchComboBox<T>({
+  id,
+  titleText,
+  placeholder,
+  items,
+  selectedItem,
+  itemToString,
+  getKey,
+  isLoading,
+  onSearch,
+  onSelect,
+  invalid,
+  invalidText,
+}: AsyncSearchComboBoxProps<T>) {
+  const { t } = useTranslation();
+  const mergedItems = useMemo(() => includeSelectedItem(items, selectedItem, getKey), [items, selectedItem, getKey]);
+
+  return (
+    <ResponsiveWrapper>
+      <div className={styles.searchField}>
+        <ComboBox<T>
+          id={id}
+          titleText={titleText}
+          placeholder={placeholder}
+          items={mergedItems}
+          itemToString={itemToString}
+          selectedItem={selectedItem}
+          onInputChange={(value) => {
+            if (isSelectionEcho(value, mergedItems, itemToString)) {
+              return;
+            }
+            onSearch(value);
+          }}
+          shouldFilterItem={() => true}
+          onChange={({ selectedItem: selection }) => onSelect(selection ?? null)}
+          invalid={invalid}
+          invalidText={invalidText}
+        />
+        <div className={styles.searchStatus}>
+          {isLoading ? <InlineLoading description={t('searching', 'Searching...')} /> : null}
+        </div>
+      </div>
+    </ResponsiveWrapper>
+  );
+}
+
+interface CodeComboBoxProps {
+  id: string;
+  titleText: string;
+  placeholder: string;
+  items: CodeOption[];
+  value: string;
+  onChange: (code: string) => void;
+  invalid?: boolean;
+  invalidText?: string;
+}
+
+/**
+ * A ComboBox backed by eTIMS code-list options (tax type, item type, quantity/packaging unit,
+ * country). The form stores the plain code string while the control renders the resolved option.
+ */
+export function CodeComboBox({
+  id,
+  titleText,
+  placeholder,
+  items,
+  value,
+  onChange,
+  invalid,
+  invalidText,
+}: CodeComboBoxProps) {
+  return (
+    <ComboBox<CodeOption>
+      id={id}
+      titleText={titleText}
+      placeholder={placeholder}
+      items={items}
+      itemToString={formatCodeOption}
+      selectedItem={resolveCodeOption(items, value)}
+      onChange={({ selectedItem }) => onChange(selectedItem?.code ?? '')}
+      invalid={invalid}
+      invalidText={invalidText}
+    />
+  );
+}

package/src/item-mapping/etims-item-mapping-form.schema.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+
+export const etimsItemMappingFormSchema = z
+  .object({
+    sourceType: z.enum(['billableService', 'stockItem']),
+    billableServiceId: z.number().int().positive().nullable().optional(),
+    stockItemId: z.number().int().positive().nullable().optional(),
+    itemName: z.string().trim().min(1, 'Item name is required'),
+    itemClassCode: z.string().trim().min(1, 'Item class is required'),
+    taxType: z.string().trim().min(1, 'Tax type is required'),
+    itemType: z.string().trim().min(1, 'Item type is required'),
+    countryCode: z.string().trim().min(1, 'Country is required'),
+    quantityUnit: z.string().trim().min(1, 'Quantity unit is required'),
+    packagingUnit: z.string().trim().min(1, 'Packaging unit is required'),
+    defaultSellingPrice: z.number().nonnegative().nullable().optional(),
+  })
+  .superRefine((value, context) => {
+    if (value.sourceType === 'billableService' && !value.billableServiceId) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['billableServiceId'],
+        message: 'Select a billable service',
+      });
+    }
+
+    if (value.sourceType === 'stockItem' && !value.stockItemId) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['stockItemId'],
+        message: 'Select a stock item',
+      });
+    }
+  });
+
+export type EtimsItemMappingFormValues = z.infer<typeof etimsItemMappingFormSchema>;