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

package/src/item-mapping/etims-item-mapping.resource.ts

@@ -0,0 +1,318 @@
+import { type FetchResponse, openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import { useMemo } from 'react';
+import useSWR from 'swr';
+import type { EtimsCode, EtimsItemClass } from '../reference-data/etims-reference-data.types';
+import type {
+  BillableServiceOption,
+  CodeOption,
+  EtimsItemMapping,
+  EtimsItemMappingPayload,
+  EtimsRegistrationResult,
+  ItemClassOption,
+  ServicePrice,
+  StockItemOption,
+} from './etims-item-mapping.types';
+
+export const etimsItemMappingUrl = `${restBaseUrl}/cashier/etimsItemMapping`;
+export const etimsItemRegistrationUrl = `${restBaseUrl}/cashier/etimsItemRegistration`;
+
+const TAX_TYPE_CATEGORY = '04';
+const QUANTITY_UNIT_CATEGORY = '10';
+const PACKAGING_UNIT_CATEGORY = '17';
+
+const ITEM_TYPE_FALLBACKS: CodeOption[] = [
+  { code: '1', name: 'Raw Material' },
+  { code: '2', name: 'Finished Product' },
+  { code: '3', name: 'Service without stock' },
+];
+
+const matchesCategory = (code: EtimsCode, needles: string[]) => {
+  const category = `${code.codeCategory ?? ''} ${code.codeCategoryName ?? ''}`.toLowerCase();
+  return needles.some((needle) => category.includes(needle));
+};
+
+const extractErrorMessage = async (response: FetchResponse, fallback: string) => {
+  const payload =
+    (response.data as { error?: string | { message?: string; detail?: string } } | undefined) ??
+    (await response.json().catch(() => ({})));
+  if (typeof payload?.error === 'string' && payload.error.trim()) {
+    return payload.error;
+  }
+
+  if (payload?.error && typeof payload.error === 'object') {
+    return payload.error.message ?? payload.error.detail ?? fallback;
+  }
+
+  return fallback;
+};
+
+const requireOk = async <T>(response: FetchResponse<T>, fallback: string) => {
+  if (!response.ok) {
+    throw new Error(await extractErrorMessage(response, fallback));
+  }
+
+  return response.data;
+};
+
+export function useEtimsItemMappings() {
+  const url = `${etimsItemMappingUrl}?v=default&limit=100`;
+  const { data, error, isLoading, isValidating, mutate } = useSWR<FetchResponse<{ results: Array<EtimsItemMapping> }>>(
+    url,
+    openmrsFetch,
+  );
+
+  return {
+    mappings: data?.data?.results ?? [],
+    error,
+    isLoading,
+    isValidating,
+    mutate,
+  };
+}
+
+export function useEtimsCodeOptions() {
+  const params = new URLSearchParams({
+    v: 'default',
+    active: 'true',
+    catalog: 'CODE_LIST',
+    limit: '100',
+  });
+  const {
+    data,
+    error: catalogError,
+    isLoading: isCatalogLoading,
+  } = useSWR<FetchResponse<{ results: Array<EtimsCode> }>>(
+    `${restBaseUrl}/cashier/etimsCode?${params.toString()}`,
+    openmrsFetch,
+  );
+
+  const {
+    data: taxTypeData,
+    error: taxTypeError,
+    isLoading: areTaxTypesLoading,
+  } = useSWR<FetchResponse<{ results: Array<EtimsCode> }>>(
+    `${restBaseUrl}/cashier/etimsCode?codeCategory=${TAX_TYPE_CATEGORY}`,
+    openmrsFetch,
+  );
+  const {
+    data: quantityUnitData,
+    error: quantityUnitError,
+    isLoading: areQuantityUnitsLoading,
+  } = useSWR<FetchResponse<{ results: Array<EtimsCode> }>>(
+    `${restBaseUrl}/cashier/etimsCode?codeCategory=${QUANTITY_UNIT_CATEGORY}`,
+    openmrsFetch,
+  );
+  const {
+    data: packagingUnitData,
+    error: packagingUnitError,
+    isLoading: arePackagingUnitsLoading,
+  } = useSWR<FetchResponse<{ results: Array<EtimsCode> }>>(
+    `${restBaseUrl}/cashier/etimsCode?codeCategory=${PACKAGING_UNIT_CATEGORY}`,
+    openmrsFetch,
+  );
+
+  const codes = (data?.data?.results ?? []).filter((code): code is EtimsCode & CodeOption => Boolean(code.code));
+  const taxTypes = (taxTypeData?.data?.results ?? []).filter((code): code is EtimsCode & CodeOption =>
+    Boolean(code.code),
+  );
+  const quantityUnits = (quantityUnitData?.data?.results ?? []).filter((code): code is EtimsCode & CodeOption =>
+    Boolean(code.code),
+  );
+  const packagingUnits = (packagingUnitData?.data?.results ?? []).filter((code): code is EtimsCode & CodeOption =>
+    Boolean(code.code),
+  );
+
+  return {
+    taxTypes,
+    itemTypes: (() => {
+      const catalogTypes = codes.filter((code) => matchesCategory(code, ['item type', 'product type']));
+      return catalogTypes.length > 0 ? catalogTypes : ITEM_TYPE_FALLBACKS;
+    })(),
+    quantityUnits,
+    packagingUnits,
+    countries: codes.filter((code) => matchesCategory(code, ['country'])),
+    error: catalogError ?? taxTypeError ?? quantityUnitError ?? packagingUnitError,
+    isLoading: isCatalogLoading || areTaxTypesLoading || areQuantityUnitsLoading || arePackagingUnitsLoading,
+  };
+}
+
+export function useEtimsItemClassOptions(searchTerm?: string) {
+  const params = new URLSearchParams({ v: 'default', active: 'true', limit: '50' });
+  const trimmed = searchTerm?.trim();
+
+  if (trimmed) {
+    params.set('q', trimmed);
+  }
+
+  const { data, error, isLoading } = useSWR<FetchResponse<{ results: Array<EtimsItemClass> }>>(
+    `${restBaseUrl}/cashier/etimsItemClass?${params.toString()}`,
+    openmrsFetch,
+    { keepPreviousData: true },
+  );
+
+  return {
+    itemClasses: (data?.data?.results ?? []).filter((item): item is EtimsItemClass & ItemClassOption =>
+      Boolean(item.itemClassCode),
+    ),
+    error,
+    isLoading,
+  };
+}
+
+export function useBillableServiceOptions(searchTerm?: string) {
+  const trimmed = searchTerm?.trim() ?? '';
+  const params = new URLSearchParams({
+    v: 'custom:(uuid,id,name,shortName,serviceStatus,servicePrices:(uuid,name,price,paymentMode:(uuid,name)),stockItem:(uuid,display))',
+    status: 'ENABLED',
+    limit: '15',
+  });
+
+  if (trimmed) {
+    params.set('q', trimmed);
+  }
+
+  const { data, error, isLoading } = useSWR<FetchResponse<{ results: Array<BillableServiceOption> }>>(
+    trimmed ? `${restBaseUrl}/cashier/billableService?${params.toString()}` : null,
+    openmrsFetch,
+    { keepPreviousData: true },
+  );
+
+  return {
+    billableServices: data?.data?.results ?? [],
+    error,
+    isLoading,
+  };
+}
+
+export function useStockItemOptions(searchTerm?: string) {
+  const trimmed = searchTerm?.trim() ?? '';
+  const params = new URLSearchParams({
+    v: 'default',
+    limit: '15',
+  });
+
+  if (trimmed) {
+    params.set('q', trimmed);
+  }
+
+  const { data, error, isLoading } = useSWR<FetchResponse<{ results: Array<StockItemOption> }>>(
+    trimmed ? `${restBaseUrl}/stockmanagement/stockitem?${params.toString()}` : null,
+    openmrsFetch,
+    { keepPreviousData: true },
+  );
+
+  return {
+    stockItems: data?.data?.results ?? [],
+    error,
+    isLoading,
+  };
+}
+
+export async function saveEtimsItemMapping(payload: EtimsItemMappingPayload, uuid?: string) {
+  const url = uuid ? `${etimsItemMappingUrl}/${uuid}` : etimsItemMappingUrl;
+  const response = await openmrsFetch<EtimsItemMapping>(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+
+  return requireOk(response, 'Failed to save eTIMS item mapping');
+}
+
+export async function voidEtimsItemMapping(uuid: string, reason: string) {
+  const params = new URLSearchParams({ reason });
+  const response = await openmrsFetch(`${etimsItemMappingUrl}/${uuid}?${params.toString()}`, {
+    method: 'DELETE',
+  });
+
+  return requireOk(response, 'Failed to void eTIMS item mapping');
+}
+
+export async function registerEtimsItemMapping(uuid: string) {
+  const response = await openmrsFetch<EtimsRegistrationResult>(`${etimsItemMappingUrl}/${uuid}/registration`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ allocateItemCode: true }),
+  });
+
+  return requireOk(response, 'Failed to register eTIMS item with KRA');
+}
+
+export async function registerEtimsItemMappings(mappingUuids: string[]) {
+  const response = await openmrsFetch<EtimsRegistrationResult>(etimsItemRegistrationUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ mappingUuids }),
+  });
+
+  return requireOk(response, 'Failed to register selected eTIMS items with KRA');
+}
+
+export async function registerAllEtimsItemMappings() {
+  const response = await openmrsFetch<EtimsRegistrationResult>(etimsItemRegistrationUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ all: true }),
+  });
+
+  return requireOk(response, 'Failed to register eTIMS items with KRA');
+}
+
+export const formatCodeOption = (item?: CodeOption | null) => {
+  if (!item) {
+    return '';
+  }
+
+  return item.name ? `${item.code} — ${item.name}` : item.code;
+};
+
+export const formatItemClassOption = (item?: ItemClassOption | null) => {
+  if (!item) {
+    return '';
+  }
+
+  return item.name ? `${item.itemClassCode} — ${item.name}` : item.itemClassCode;
+};
+
+export const resolveCodeOption = (items: CodeOption[], value?: string | null): CodeOption | null => {
+  if (!value) {
+    return null;
+  }
+
+  return items.find((item) => item.code === value) ?? { code: value, name: value };
+};
+
+export const resolveItemClassOption = (items: ItemClassOption[], value?: string | null): ItemClassOption | null => {
+  if (!value) {
+    return null;
+  }
+
+  return items.find((item) => item.itemClassCode === value) ?? { itemClassCode: value, name: value };
+};
+
+export const getServicePriceAmount = (item?: ServicePrice | null): number | null => {
+  const price = item?.price;
+  if (price === null || price === undefined || price === '') {
+    return null;
+  }
+
+  const numericPrice = Number(price);
+  return Number.isFinite(numericPrice) ? numericPrice : null;
+};
+
+export const formatServicePrice = (item?: ServicePrice | null): string => {
+  if (!item) {
+    return '';
+  }
+
+  const paymentMode = typeof item.paymentMode === 'string' ? item.paymentMode : item.paymentMode?.name;
+  const label = item.name ?? paymentMode ?? '';
+  const amount = getServicePriceAmount(item);
+  const amountText = amount === null ? '' : amount.toLocaleString();
+
+  if (label && amountText) {
+    return `${label} — ${amountText}`;
+  }
+
+  return label || amountText;
+};

package/src/item-mapping/etims-item-mapping.types.ts

@@ -0,0 +1,92 @@
+export type EtimsRegistrationStatus = 'PENDING' | 'REGISTERED' | 'FAILED';
+
+export type EtimsItemSourceType = 'billableService' | 'stockItem';
+
+export interface EtimsItemMapping {
+  uuid: string;
+  display?: string;
+  billableServiceId?: number | null;
+  stockItemId?: number | null;
+  businessPin?: string | null;
+  branchId?: string | null;
+  itemCode?: string | null;
+  itemName?: string | null;
+  itemClassCode?: string | null;
+  taxType?: string | null;
+  registrationStatus?: EtimsRegistrationStatus | string | null;
+  countryCode?: string | null;
+  itemType?: string | null;
+  quantityUnit?: string | null;
+  packagingUnit?: string | null;
+  defaultSellingPrice?: number | null;
+  registrationResultCode?: string | null;
+  registrationResultMessage?: string | null;
+  registeredAt?: string | null;
+  lastVerifiedAt?: string | null;
+  voided?: boolean;
+  dateCreated?: string | null;
+}
+
+export interface EtimsItemMappingPayload {
+  billableServiceId?: number | null;
+  stockItemId?: number | null;
+  businessPin?: string | null;
+  branchId?: string | null;
+  itemName: string;
+  itemClassCode: string;
+  countryCode: string;
+  itemType: string;
+  quantityUnit: string;
+  packagingUnit: string;
+  taxType: string;
+  defaultSellingPrice?: number | null | string;
+}
+
+export interface EtimsRegistrationResult {
+  registered: number;
+  skipped: number;
+  failed: number;
+  message?: string | null;
+  total: number;
+}
+
+export interface ServicePrice {
+  uuid?: string;
+  name?: string;
+  price?: number | string | null;
+  paymentMode?: { uuid?: string; name?: string } | string | null;
+}
+
+export interface BillableServiceOption {
+  uuid: string;
+  id?: number;
+  name?: string;
+  display?: string;
+  serviceStatus?: string;
+  servicePrices?: Array<ServicePrice>;
+  stockItem?: { uuid?: string; display?: string } | null;
+}
+
+export interface StockItemOption {
+  uuid: string;
+  id?: number;
+  commonName?: string;
+  display?: string;
+  purchasePrice?: number | null;
+}
+
+export interface CodeOption {
+  uuid?: string;
+  code: string;
+  name?: string | null;
+  display?: string;
+  codeCategory?: string | null;
+  codeCategoryName?: string | null;
+}
+
+export interface ItemClassOption {
+  uuid?: string;
+  itemClassCode: string;
+  name?: string | null;
+  display?: string;
+}

package/src/item-mapping/register-item-mapping.modal.tsx

@@ -0,0 +1,113 @@
+import React, { useState } from 'react';
+import { Button, InlineLoading } from '@carbon/react';
+import { showSnackbar } from '@openmrs/esm-framework';
+import { useTranslation } from 'react-i18next';
+import {
+  registerAllEtimsItemMappings,
+  registerEtimsItemMapping,
+  registerEtimsItemMappings,
+} from './etims-item-mapping.resource';
+import type { TFunction } from 'i18next';
+import type { EtimsRegistrationResult } from './etims-item-mapping.types';
+
+type RegisterScope = 'one' | 'selected' | 'all';
+
+type RegisterItemMappingModalProps = {
+  close: () => void;
+  scope: RegisterScope;
+  uuid?: string;
+  mappingUuids?: string[];
+  itemName?: string;
+  onRegistered: () => void;
+};
+
+const describeResult = (result: EtimsRegistrationResult, t: TFunction) =>
+  t('registrationResultSummary', '{{registered}} registered, {{skipped}} skipped, {{failed}} failed', {
+    registered: result.registered,
+    skipped: result.skipped,
+    failed: result.failed,
+  });
+
+const RegisterItemMappingModal: React.FC<RegisterItemMappingModalProps> = ({
+  close,
+  scope,
+  uuid,
+  mappingUuids = [],
+  itemName,
+  onRegistered,
+}) => {
+  const { t } = useTranslation();
+  const [isRegistering, setIsRegistering] = useState(false);
+
+  const heading =
+    scope === 'all'
+      ? t('syncAllToKra', 'Sync all to KRA')
+      : scope === 'selected'
+      ? t('syncSelectedToKra', 'Sync selected to KRA')
+      : t('syncToKra', 'Sync to KRA');
+
+  const message =
+    scope === 'all'
+      ? t(
+          'syncAllToKraConfirmation',
+          'Submit every mapped item that still needs registration or has changed since the last successful KRA sync. Already registered unchanged items are skipped.',
+        )
+      : scope === 'selected'
+      ? t(
+          'syncSelectedToKraConfirmation',
+          'Submit {{count}} selected mapping(s) to KRA. Unchanged registered items are skipped.',
+          { count: mappingUuids.length },
+        )
+      : t('syncOneToKraConfirmation', 'Submit "{{itemName}}" to KRA for item registration.', {
+          itemName: itemName ?? t('thisMapping', 'this mapping'),
+        });
+
+  const handleRegister = async () => {
+    setIsRegistering(true);
+    try {
+      const result =
+        scope === 'all'
+          ? await registerAllEtimsItemMappings()
+          : scope === 'selected'
+          ? await registerEtimsItemMappings(mappingUuids)
+          : await registerEtimsItemMapping(uuid as string);
+
+      showSnackbar({
+        kind: result.failed > 0 ? 'warning' : 'success',
+        title: t('kraSyncComplete', 'KRA sync complete'),
+        subtitle: result.message || describeResult(result, t),
+      });
+      onRegistered();
+      close();
+    } catch (error: any) {
+      showSnackbar({
+        kind: 'error',
+        title: t('kraSyncError', 'Unable to sync items to KRA'),
+        subtitle: error?.message,
+      });
+    } finally {
+      setIsRegistering(false);
+    }
+  };
+
+  return (
+    <>
+      <div className="cds--modal-header">
+        <h3 className="cds--modal-header__heading">{heading}</h3>
+      </div>
+      <div className="cds--modal-content">
+        <p>{message}</p>
+      </div>
+      <div className="cds--modal-footer">
+        <Button kind="secondary" onClick={close} disabled={isRegistering}>
+          {t('cancel', 'Cancel')}
+        </Button>
+        <Button kind="primary" onClick={handleRegister} disabled={isRegistering}>
+          {isRegistering ? <InlineLoading description={t('syncing', 'Syncing...')} /> : heading}
+        </Button>
+      </div>
+    </>
+  );
+};
+
+export default RegisterItemMappingModal;

package/src/item-mapping/void-item-mapping.modal.tsx

@@ -0,0 +1,80 @@
+import React, { useState } from 'react';
+import { Button, InlineLoading, TextInput } from '@carbon/react';
+import { showSnackbar } from '@openmrs/esm-framework';
+import { useTranslation } from 'react-i18next';
+import { voidEtimsItemMapping } from './etims-item-mapping.resource';
+
+type VoidItemMappingModalProps = {
+  close: () => void;
+  uuid: string;
+  itemName: string;
+  onVoided: () => void;
+};
+
+const VoidItemMappingModal: React.FC<VoidItemMappingModalProps> = ({ close, uuid, itemName, onVoided }) => {
+  const { t } = useTranslation();
+  const [reason, setReason] = useState('');
+  const [isVoiding, setIsVoiding] = useState(false);
+
+  const handleVoid = async () => {
+    const trimmedReason = reason.trim();
+    if (!trimmedReason) {
+      return;
+    }
+
+    setIsVoiding(true);
+    try {
+      await voidEtimsItemMapping(uuid, trimmedReason);
+      showSnackbar({
+        kind: 'success',
+        title: t('itemMappingVoided', 'Item mapping voided'),
+        subtitle: t('itemMappingVoidedSubtitle', '{{itemName}} was voided.', { itemName }),
+      });
+      onVoided();
+      close();
+    } catch (error: any) {
+      showSnackbar({
+        kind: 'error',
+        title: t('itemMappingVoidError', 'Unable to void item mapping'),
+        subtitle: error?.message,
+      });
+    } finally {
+      setIsVoiding(false);
+    }
+  };
+
+  return (
+    <>
+      <div className="cds--modal-header">
+        <h3 className="cds--modal-header__heading">{t('voidItemMapping', 'Void item mapping')}</h3>
+      </div>
+      <div className="cds--modal-content">
+        <p>
+          {t(
+            'voidItemMappingConfirmation',
+            'Void the mapping for "{{itemName}}"? This mapping will no longer be used for KRA registration.',
+            {
+              itemName,
+            },
+          )}
+        </p>
+        <TextInput
+          id="void-reason"
+          labelText={t('voidReason', 'Reason')}
+          value={reason}
+          onChange={(event) => setReason(event.target.value)}
+        />
+      </div>
+      <div className="cds--modal-footer">
+        <Button kind="secondary" onClick={close} disabled={isVoiding}>
+          {t('cancel', 'Cancel')}
+        </Button>
+        <Button kind="danger" onClick={handleVoid} disabled={isVoiding || !reason.trim()}>
+          {isVoiding ? <InlineLoading description={t('voiding', 'Voiding...')} /> : t('void', 'Void')}
+        </Button>
+      </div>
+    </>
+  );
+};
+
+export default VoidItemMappingModal;

package/src/left-panel-link.component.tsx

@@ -0,0 +1,39 @@
+import React, { type ComponentType } from 'react';
+import { ConfigurableLink, MaybeIcon, type IconId } from '@openmrs/esm-framework';
+import { useTranslation } from 'react-i18next';
+import { BrowserRouter, useLocation } from 'react-router-dom';
+import styles from './left-panel-link.scss';
+
+interface LinkConfig {
+  title: string;
+  name?: string;
+  icon?: IconId;
+}
+
+function LinkExtension({ config }: Readonly<{ config: LinkConfig }>) {
+  const { t } = useTranslation();
+  const location = useLocation();
+  const { name, title, icon } = config;
+  const etimsBasePath = `${window.getOpenmrsSpaBase()}etims`;
+  const targetPath = name ? `${etimsBasePath}/${name}` : etimsBasePath;
+  const pathAfterEtims = location.pathname.replace(etimsBasePath, '').replace(/^\//, '');
+  const isActive = name ? pathAfterEtims === name || pathAfterEtims.startsWith(`${name}/`) : pathAfterEtims === '';
+
+  return (
+    <ConfigurableLink to={targetPath} className={`cds--side-nav__link${isActive ? ' active-left-nav-link' : ''}`}>
+      <span className={styles.menu}>
+        <MaybeIcon icon={icon} className={styles.icon} size={16} />
+        <span>{t(title)}</span>
+      </span>
+    </ConfigurableLink>
+  );
+}
+
+export const createLeftPanelLink = (config: LinkConfig): ComponentType<unknown> =>
+  function EtimsLeftPanelLink() {
+    return (
+      <BrowserRouter>
+        <LinkExtension config={config} />
+      </BrowserRouter>
+    );
+  };

package/src/left-panel-link.scss

@@ -0,0 +1,12 @@
+@use '@carbon/layout';
+
+.menu {
+  display: flex;
+  align-items: center;
+  gap: layout.$spacing-04;
+}
+
+.icon {
+  flex-shrink: 0;
+  fill: currentColor;
+}