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

package/src/transaction/etims-transaction.types.ts

@@ -0,0 +1,78 @@
+export type EtimsTransactionStatus =
+  | 'PENDING'
+  | 'PROCESSING'
+  | 'SUBMITTED'
+  | 'CONFIRMED'
+  | 'RETRY'
+  | 'RECONCILIATION_REQUIRED'
+  | 'ACTION_REQUIRED'
+  | 'PERMANENTLY_FAILED'
+  | 'CANCELLED';
+
+export type EtimsTransactionType = 'ORIGINAL_SALE' | 'CREDIT_NOTE' | 'REPLACEMENT_SALE';
+
+export type EtimsReconciliationOverrideAction = 'CONFIRM' | 'REQUEUE' | 'PERMANENTLY_FAIL';
+
+export interface EtimsTransaction {
+  uuid: string;
+  display?: string;
+  billId?: number | null;
+  transactionType?: EtimsTransactionType | null;
+  status?: EtimsTransactionStatus | null;
+  revisionNumber?: number | null;
+  traderInvoiceNumber?: string | null;
+  kraInvoiceNumber?: string | null;
+  resultCode?: string | null;
+  resultMessage?: string | null;
+  failureCategory?: string | null;
+  attemptCount?: number | null;
+  dateCreated?: string | null;
+  cuInvoiceNumber?: string | null;
+  kraReceiptNumber?: string | null;
+  qrUrl?: string | null;
+  sdcId?: string | null;
+  mrcNumber?: string | null;
+  confirmedAt?: string | null;
+  nextAttemptAt?: string | null;
+  originalTransactionId?: number | null;
+  receiptSignature?: string | null;
+  publicationDate?: string | null;
+}
+
+export interface EtimsTransactionSummary {
+  uuid: string;
+  billId?: number | null;
+  transactionType?: EtimsTransactionType | null;
+  status?: EtimsTransactionStatus | null;
+  kraInvoiceNumber?: string | null;
+  traderInvoiceNumber?: string | null;
+  resultCode?: string | null;
+  resultMessage?: string | null;
+  cuInvoiceNumber?: string | null;
+  receiptNumber?: string | null;
+  confirmedAt?: string | null;
+}
+
+export interface EtimsReconciliationOverride {
+  uuid: string;
+  action?: EtimsReconciliationOverrideAction | null;
+  previousStatus?: string | null;
+  newStatus?: string | null;
+  reason?: string | null;
+  evidenceReference?: string | null;
+  operatorUuid?: string | null;
+  dateCreated?: string | null;
+}
+
+export interface EtimsReconciliationOverridePayload {
+  action: EtimsReconciliationOverrideAction;
+  reason: string;
+  evidenceReference: string;
+  cuInvoiceNumber?: string;
+  receiptNumber?: string;
+  receiptSignature?: string;
+  sdcId?: string;
+  mrcNumber?: string;
+  qrUrl?: string;
+  publicationDate?: string;
+}

package/src/transaction/override-reconciliation.modal.scss

@@ -0,0 +1,7 @@
+@use '@carbon/layout';
+
+.content {
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-05;
+}

package/src/transaction/override-reconciliation.modal.tsx

@@ -0,0 +1,203 @@
+import React, { useMemo, useState } from 'react';
+import { Button, Dropdown, InlineLoading, TextArea, TextInput } from '@carbon/react';
+import { showSnackbar } from '@openmrs/esm-framework';
+import { useTranslation } from 'react-i18next';
+import { overrideEtimsReconciliation } from './etims-transaction.resource';
+import type { EtimsReconciliationOverrideAction, EtimsReconciliationOverridePayload } from './etims-transaction.types';
+import styles from './override-reconciliation.modal.scss';
+
+type OverrideReconciliationModalProps = {
+  close: () => void;
+  uuid: string;
+  displayName: string;
+  kraInvoiceNumber?: string | null;
+  onComplete: () => void;
+};
+
+type ActionItem = { id: EtimsReconciliationOverrideAction; label: string };
+
+const OverrideReconciliationModal: React.FC<OverrideReconciliationModalProps> = ({
+  close,
+  uuid,
+  displayName,
+  kraInvoiceNumber,
+  onComplete,
+}) => {
+  const { t } = useTranslation();
+  const [action, setAction] = useState<EtimsReconciliationOverrideAction>('REQUEUE');
+  const [reason, setReason] = useState('');
+  const [evidenceReference, setEvidenceReference] = useState('');
+  const [cuInvoiceNumber, setCuInvoiceNumber] = useState('');
+  const [receiptNumber, setReceiptNumber] = useState('');
+  const [receiptSignature, setReceiptSignature] = useState('');
+  const [sdcId, setSdcId] = useState('');
+  const [mrcNumber, setMrcNumber] = useState('');
+  const [qrUrl, setQrUrl] = useState('');
+  const [publicationDate, setPublicationDate] = useState('');
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const actionItems: ActionItem[] = useMemo(
+    () => [
+      { id: 'REQUEUE', label: t('requeue', 'Requeue') },
+      { id: 'CONFIRM', label: t('confirm', 'Confirm') },
+      { id: 'PERMANENTLY_FAIL', label: t('permanentlyFail', 'Permanently fail') },
+    ],
+    [t],
+  );
+
+  const confirmationComplete =
+    Boolean(cuInvoiceNumber.trim()) &&
+    Boolean(receiptNumber.trim()) &&
+    Boolean(receiptSignature.trim()) &&
+    Boolean(sdcId.trim()) &&
+    Boolean(mrcNumber.trim()) &&
+    Boolean(qrUrl.trim()) &&
+    Boolean(publicationDate.trim());
+
+  const canSubmit =
+    Boolean(reason.trim()) &&
+    Boolean(evidenceReference.trim()) &&
+    (action !== 'CONFIRM' || (Boolean(kraInvoiceNumber) && confirmationComplete));
+
+  const handleSubmit = async () => {
+    if (!canSubmit) {
+      return;
+    }
+
+    const payload: EtimsReconciliationOverridePayload = {
+      action,
+      reason: reason.trim(),
+      evidenceReference: evidenceReference.trim(),
+    };
+
+    if (action === 'CONFIRM') {
+      payload.cuInvoiceNumber = cuInvoiceNumber.trim();
+      payload.receiptNumber = receiptNumber.trim();
+      payload.receiptSignature = receiptSignature.trim();
+      payload.sdcId = sdcId.trim();
+      payload.mrcNumber = mrcNumber.trim();
+      payload.qrUrl = qrUrl.trim();
+      payload.publicationDate = publicationDate.trim();
+    }
+
+    setIsSubmitting(true);
+    try {
+      const result = await overrideEtimsReconciliation(uuid, payload);
+      showSnackbar({
+        kind: 'success',
+        title: t('overrideRecorded', 'Override recorded'),
+        subtitle:
+          result.resultMessage ?? t('transactionStatusUpdated', 'Status: {{status}}', { status: result.status }),
+      });
+      onComplete();
+      close();
+    } catch (error: any) {
+      showSnackbar({
+        kind: 'error',
+        title: t('overrideError', 'Unable to record override'),
+        subtitle: error?.message,
+      });
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  return (
+    <>
+      <div className="cds--modal-header">
+        <h3 className="cds--modal-header__heading">{t('recordOverride', 'Record override')}</h3>
+      </div>
+      <div className={`cds--modal-content ${styles.content}`}>
+        <p>
+          {t(
+            'recordOverrideConfirmation',
+            'Record an evidence-based status change for "{{displayName}}". Gateway lookup should be tried first. Confirm requires a reserved KRA invoice number.',
+            { displayName },
+          )}
+        </p>
+        <Dropdown
+          id="override-action"
+          titleText={t('overrideAction', 'Action')}
+          label={t('selectOverrideAction', 'Select action')}
+          items={actionItems}
+          itemToString={(item) => item?.label ?? ''}
+          selectedItem={actionItems.find((item) => item.id === action)}
+          onChange={({ selectedItem }) => setAction(selectedItem?.id ?? 'REQUEUE')}
+        />
+        <TextArea
+          id="override-reason"
+          labelText={t('reason', 'Reason')}
+          value={reason}
+          onChange={(event) => setReason(event.target.value)}
+        />
+        <TextInput
+          id="override-evidence"
+          labelText={t('evidenceReference', 'Evidence')}
+          value={evidenceReference}
+          onChange={(event) => setEvidenceReference(event.target.value)}
+        />
+        {action === 'CONFIRM' ? (
+          <>
+            <TextInput
+              id="override-cu-invoice"
+              labelText={t('cuInvoiceNumber', 'CU invoice')}
+              value={cuInvoiceNumber}
+              onChange={(event) => setCuInvoiceNumber(event.target.value)}
+            />
+            <TextInput
+              id="override-receipt-number"
+              labelText={t('receiptNumber', 'Receipt number')}
+              value={receiptNumber}
+              onChange={(event) => setReceiptNumber(event.target.value)}
+            />
+            <TextInput
+              id="override-receipt-signature"
+              labelText={t('receiptSignature', 'Receipt signature')}
+              value={receiptSignature}
+              onChange={(event) => setReceiptSignature(event.target.value)}
+            />
+            <TextInput
+              id="override-sdc-id"
+              labelText={t('sdcId', 'SDC ID')}
+              value={sdcId}
+              onChange={(event) => setSdcId(event.target.value)}
+            />
+            <TextInput
+              id="override-mrc-number"
+              labelText={t('mrcNumber', 'MRC number')}
+              value={mrcNumber}
+              onChange={(event) => setMrcNumber(event.target.value)}
+            />
+            <TextInput
+              id="override-qr-url"
+              labelText={t('qrUrl', 'QR URL')}
+              value={qrUrl}
+              onChange={(event) => setQrUrl(event.target.value)}
+            />
+            <TextInput
+              id="override-publication-date"
+              labelText={t('publicationDate', 'Publication date')}
+              helperText={t('publicationDateHelper', 'ISO datetime, for example 2026-08-13T10:15:30.000+0300')}
+              value={publicationDate}
+              onChange={(event) => setPublicationDate(event.target.value)}
+            />
+          </>
+        ) : null}
+      </div>
+      <div className="cds--modal-footer">
+        <Button kind="secondary" onClick={close} disabled={isSubmitting}>
+          {t('cancel', 'Cancel')}
+        </Button>
+        <Button kind="primary" onClick={handleSubmit} disabled={isSubmitting || !canSubmit}>
+          {isSubmitting ? (
+            <InlineLoading description={t('saving', 'Saving...')} />
+          ) : (
+            t('recordOverride', 'Record override')
+          )}
+        </Button>
+      </div>
+    </>
+  );
+};
+
+export default OverrideReconciliationModal;

package/translations/am.json

@@ -0,0 +1,129 @@
+{
+  "actionRequired": "Action required",
+  "active": "Active",
+  "addItemMapping": "Add item mapping",
+  "allStatuses": "All statuses",
+  "apiKeyConfigured": "API key configured",
+  "attemptCount": "Attempts",
+  "baseUrl": "Base URL",
+  "billableServiceSource": "Service #{{id}}",
+  "billId": "Bill ID",
+  "branchId": "Branch ID",
+  "businessPin": "Business PIN",
+  "cancelled": "Cancelled",
+  "classListSync": "Class list sync",
+  "code": "Code",
+  "codeCategory": "Category",
+  "codeCategoryName": "Category name",
+  "codeListSync": "Code list sync",
+  "configuration": "Configuration",
+  "configure": "Configure",
+  "confirmed": "Confirmed",
+  "confirmedAt": "Confirmed at",
+  "connectionOverview": "Connection overview",
+  "contractVersion": "Contract version",
+  "createCreditNote": "Create credit note",
+  "creditNotes": "Credit notes",
+  "creditNotesDescription": "Raise credit notes against confirmed eTIMS invoices and track their submission to KRA.",
+  "dateCreated": "Date created",
+  "description": "Description",
+  "downloading": "Downloading...",
+  "downloadTaxInvoice": "Download tax invoice",
+  "edit": "Edit",
+  "environment": "Environment",
+  "etims": "eTIMS",
+  "etimsCodes": "eTIMS codes",
+  "etimsCodesDescription": "Synchronized KRA reference codes such as tax types, item types, and units. Search by name, code, or category.",
+  "etimsCodesError": "eTIMS codes",
+  "eTimsConfigs": "Etims Configs",
+  "etimsEnabled": "eTIMS enabled",
+  "etimsGlobalProperties": "eTIMS global properties",
+  "etimsGlobalPropertiesDescription": "Review the global properties used by the eTIMS integration.",
+  "etimsItemClasses": "eTIMS item classes",
+  "etimsItemClassesDescription": "Synchronized KRA item classes used when mapping and registering cashier items. Search by name or item class code.",
+  "etimsItemClassesError": "eTIMS item classes",
+  "etimsLeftPanel": "eTIMS left panel",
+  "etimsStatus": "eTIMS status",
+  "failed": "Failed",
+  "gatewayHealth": "Gateway health",
+  "healthy": "Healthy",
+  "invalid": "Invalid",
+  "itemClassCode": "Item class code",
+  "itemCode": "Item code",
+  "itemMappings": "Item mappings",
+  "itemMappingsDescription": "Map cashier billable services and stock items to KRA item codes, then sync them to eTIMS.",
+  "itemMappingsError": "Item mappings",
+  "itemName": "Item name",
+  "itemsPerPage": "Items per page:",
+  "itemType": "Item type",
+  "kraInvoiceNumber": "KRA invoice",
+  "lastFailureAt": "Last failure",
+  "lastFailureMessage": "Last failure message",
+  "lastRecordCount": "Last record count",
+  "lastRequestDatetime": "Last request",
+  "lastSuccessAt": "Last success",
+  "licenceResultCode": "Licence result code",
+  "licenceStatus": "Licence",
+  "loadingEtimsStatus": "Loading eTIMS status...",
+  "minMaxItems": "{{min}}-{{max}} of {{total}} items",
+  "missingBillId": "This transaction has no bill ID",
+  "name": "Name",
+  "nextPage": "Next page",
+  "no": "No",
+  "pageRangeText_one": "of {{count}} pages",
+  "pageRangeText_other": "of {{count}} pages",
+  "pending": "Pending",
+  "permanentlyFailed": "Permanently failed",
+  "previousPage": "Previous page",
+  "processing": "Processing",
+  "property": "Property",
+  "reconcileWithKra": "Reconcile with KRA",
+  "reconciliationRequired": "Reconciliation required",
+  "recordedValue": "Recorded value",
+  "recordOverride": "Record override",
+  "referenceData": "Reference data",
+  "referenceDataSync": "Reference data sync",
+  "refreshing": "Refreshing...",
+  "refreshStatus": "Refresh status",
+  "registered": "Registered",
+  "registeredAt": "Registered at",
+  "registrationStatus": "Registration",
+  "resultMessage": "Last result",
+  "retry": "Retry",
+  "retrySubmission": "Retry submission",
+  "rowActions": "Row actions",
+  "sandboxValidatedContractVersion": "Sandbox validated contract version",
+  "searchCreditNotes": "Search by bill ID, invoice, or result",
+  "searchEtimsCodes": "Search eTIMS codes",
+  "searchEtimsItemClasses": "Search eTIMS item classes",
+  "searchForGlobalProperties": "Search for global properties",
+  "searchItemMappings": "Search mappings",
+  "searchTransactions": "Search by bill ID, invoice, or result",
+  "source": "Source",
+  "status": "Status",
+  "stockItemSource": "Stock #{{id}}",
+  "submitted": "Submitted",
+  "sync": "Sync",
+  "syncAllToKra": "Sync all to KRA",
+  "syncCategory": "Category",
+  "syncClassListMessage": "Synchronization of class list from KRA, this will update class list to latest version, Do you want to proceed?",
+  "syncCodeList": "Sync class list",
+  "syncCodeListMessage": "Synchronization of code list from KRA, this will update code list to latest version, Do you want to proceed?",
+  "syncHasFailures": "Needs attention",
+  "syncHealthy": "Healthy",
+  "syncSelectedToKra": "Sync selected to KRA",
+  "syncToKra": "Sync to KRA",
+  "taxInvoiceDownloaded": "Tax invoice downloaded",
+  "taxInvoiceError": "Unable to download tax invoice",
+  "taxType": "Tax type",
+  "traderInvoiceNumber": "Trader invoice",
+  "transactions": "Transactions",
+  "transactionsDescription": "Review the fiscal outbox, retry failed submissions, and reconcile ambiguous KRA results.",
+  "transactionsError": "Transactions",
+  "transactionType": "Type",
+  "unhealthy": "Unhealthy",
+  "valid": "Valid",
+  "viewDetails": "View details",
+  "void": "Void",
+  "yes": "Yes"
+}

package/translations/en.json

@@ -0,0 +1,129 @@
+{
+  "actionRequired": "Action required",
+  "active": "Active",
+  "addItemMapping": "Add item mapping",
+  "allStatuses": "All statuses",
+  "apiKeyConfigured": "API key configured",
+  "attemptCount": "Attempts",
+  "baseUrl": "Base URL",
+  "billableServiceSource": "Service #{{id}}",
+  "billId": "Bill ID",
+  "branchId": "Branch ID",
+  "businessPin": "Business PIN",
+  "cancelled": "Cancelled",
+  "classListSync": "Class list sync",
+  "code": "Code",
+  "codeCategory": "Category",
+  "codeCategoryName": "Category name",
+  "codeListSync": "Code list sync",
+  "configuration": "Configuration",
+  "configure": "Configure",
+  "confirmed": "Confirmed",
+  "confirmedAt": "Confirmed at",
+  "connectionOverview": "Connection overview",
+  "contractVersion": "Contract version",
+  "createCreditNote": "Create credit note",
+  "creditNotes": "Credit notes",
+  "creditNotesDescription": "Raise credit notes against confirmed eTIMS invoices and track their submission to KRA.",
+  "dateCreated": "Date created",
+  "description": "Description",
+  "downloading": "Downloading...",
+  "downloadTaxInvoice": "Download tax invoice",
+  "edit": "Edit",
+  "environment": "Environment",
+  "etims": "eTIMS",
+  "etimsCodes": "eTIMS codes",
+  "etimsCodesDescription": "Synchronized KRA reference codes such as tax types, item types, and units. Search by name, code, or category.",
+  "etimsCodesError": "eTIMS codes",
+  "eTimsConfigs": "Etims Configs",
+  "etimsEnabled": "eTIMS enabled",
+  "etimsGlobalProperties": "eTIMS global properties",
+  "etimsGlobalPropertiesDescription": "Review the global properties used by the eTIMS integration.",
+  "etimsItemClasses": "eTIMS item classes",
+  "etimsItemClassesDescription": "Synchronized KRA item classes used when mapping and registering cashier items. Search by name or item class code.",
+  "etimsItemClassesError": "eTIMS item classes",
+  "etimsLeftPanel": "eTIMS left panel",
+  "etimsStatus": "eTIMS status",
+  "failed": "Failed",
+  "gatewayHealth": "Gateway health",
+  "healthy": "Healthy",
+  "invalid": "Invalid",
+  "itemClassCode": "Item class",
+  "itemCode": "Item code",
+  "itemMappings": "Item mappings",
+  "itemMappingsDescription": "Map cashier billable services and stock items to KRA item codes, then sync them to eTIMS.",
+  "itemMappingsError": "Item mappings",
+  "itemName": "Item name",
+  "itemsPerPage": "Items per page:",
+  "itemType": "Item type",
+  "kraInvoiceNumber": "KRA invoice",
+  "lastFailureAt": "Last failure",
+  "lastFailureMessage": "Last failure message",
+  "lastRecordCount": "Last record count",
+  "lastRequestDatetime": "Last request",
+  "lastSuccessAt": "Last success",
+  "licenceResultCode": "Licence result code",
+  "licenceStatus": "Licence",
+  "loadingEtimsStatus": "Loading eTIMS status...",
+  "minMaxItems": "{{min}}-{{max}} of {{total}} items",
+  "missingBillId": "This transaction has no bill ID",
+  "name": "Name",
+  "nextPage": "Next page",
+  "no": "No",
+  "pageRangeText_one": "of {{count}} pages",
+  "pageRangeText_other": "of {{count}} pages",
+  "pending": "Pending",
+  "permanentlyFailed": "Permanently failed",
+  "previousPage": "Previous page",
+  "processing": "Processing",
+  "property": "Property",
+  "reconcileWithKra": "Reconcile with KRA",
+  "reconciliationRequired": "Reconciliation required",
+  "recordedValue": "Recorded value",
+  "recordOverride": "Record override",
+  "referenceData": "Reference data",
+  "referenceDataSync": "Reference data sync",
+  "refreshing": "Refreshing...",
+  "refreshStatus": "Refresh status",
+  "registered": "Registered",
+  "registeredAt": "Registered at",
+  "registrationStatus": "Registration",
+  "resultMessage": "Last result",
+  "retry": "Retry",
+  "retrySubmission": "Retry submission",
+  "rowActions": "Row actions",
+  "sandboxValidatedContractVersion": "Sandbox validated contract version",
+  "searchCreditNotes": "Search by bill ID, invoice, or result",
+  "searchEtimsCodes": "Search eTIMS codes",
+  "searchEtimsItemClasses": "Search eTIMS item classes",
+  "searchForGlobalProperties": "Search for global properties",
+  "searchItemMappings": "Search mappings",
+  "searchTransactions": "Search by bill ID, invoice, or result",
+  "source": "Source",
+  "status": "Status",
+  "stockItemSource": "Stock #{{id}}",
+  "submitted": "Submitted",
+  "sync": "Sync",
+  "syncAllToKra": "Sync all to KRA",
+  "syncCategory": "Category",
+  "syncClassListMessage": "Synchronization of class list from KRA, this will update class list to latest version, Do you want to proceed?",
+  "syncCodeList": "Sync class list",
+  "syncCodeListMessage": "Synchronization of code list from KRA, this will update code list to latest version, Do you want to proceed?",
+  "syncHasFailures": "Needs attention",
+  "syncHealthy": "Healthy",
+  "syncSelectedToKra": "Sync selected to KRA",
+  "syncToKra": "Sync to KRA",
+  "taxInvoiceDownloaded": "Tax invoice downloaded",
+  "taxInvoiceError": "Unable to download tax invoice",
+  "taxType": "Tax type",
+  "traderInvoiceNumber": "Trader invoice",
+  "transactions": "Transactions",
+  "transactionsDescription": "Review the fiscal outbox, retry failed submissions, and reconcile ambiguous KRA results.",
+  "transactionsError": "Transactions",
+  "transactionType": "Type",
+  "unhealthy": "Unhealthy",
+  "valid": "Valid",
+  "viewDetails": "View details",
+  "void": "Void",
+  "yes": "Yes"
+}