react-native-amwal-ecr 0.1.0

package/src/NativeAmwalEcr.ts

@@ -0,0 +1,28 @@
+import {
+  TurboModuleRegistry,
+  type CodegenTypes,
+  type TurboModule,
+} from 'react-native';
+
+export interface Spec extends TurboModule {
+  isReachable(request: CodegenTypes.UnsafeObject): Promise<boolean>;
+  sale(request: CodegenTypes.UnsafeObject): Promise<CodegenTypes.UnsafeObject>;
+  voidTransaction(
+    request: CodegenTypes.UnsafeObject
+  ): Promise<CodegenTypes.UnsafeObject>;
+  refund(
+    request: CodegenTypes.UnsafeObject
+  ): Promise<CodegenTypes.UnsafeObject>;
+  inquire(
+    request: CodegenTypes.UnsafeObject
+  ): Promise<CodegenTypes.UnsafeObject>;
+  inquireByReference(
+    request: CodegenTypes.UnsafeObject
+  ): Promise<CodegenTypes.UnsafeObject>;
+  receipt(
+    request: CodegenTypes.UnsafeObject
+  ): Promise<CodegenTypes.UnsafeObject>;
+  cancel(operationId: string): Promise<boolean>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('AmwalEcr');

package/src/index.tsx

@@ -0,0 +1,34 @@
+export { EcrOperation } from './EcrOperation';
+export { EcrTerminal } from './EcrTerminal';
+export {
+  normalizeInquiry,
+  normalizeReceipt,
+  normalizeResult,
+} from './normalize';
+export type {
+  EcrApproved,
+  EcrConfig,
+  EcrDatedTransactionOptions,
+  EcrDeclined,
+  EcrEnvironment,
+  EcrFailed,
+  EcrFailure,
+  EcrFailureKind,
+  EcrInquiry,
+  EcrInquiryByReferenceOptions,
+  EcrInquiryFailed,
+  EcrInquiryFound,
+  EcrInquiryNotFound,
+  EcrNextStep,
+  EcrOriginalTransactionOptions,
+  EcrReceipt,
+  EcrReceiptFailed,
+  EcrReceiptReady,
+  EcrReceiptUnavailable,
+  EcrReferenceOptions,
+  EcrRefundOptions,
+  EcrResult,
+  EcrTerminalOptions,
+  EcrTransaction,
+  EcrTransport,
+} from './types';

package/src/native.native.ts

@@ -0,0 +1 @@
+export { default as nativeEcr } from './NativeAmwalEcr';

package/src/native.ts

@@ -0,0 +1,18 @@
+import type NativeAmwalEcr from './NativeAmwalEcr';
+
+const unsupported = (): never => {
+  throw new Error(
+    "'react-native-amwal-ecr' is only supported on Android and iOS."
+  );
+};
+
+export const nativeEcr: typeof NativeAmwalEcr = {
+  isReachable: async () => unsupported(),
+  sale: async () => unsupported(),
+  voidTransaction: async () => unsupported(),
+  refund: async () => unsupported(),
+  inquire: async () => unsupported(),
+  inquireByReference: async () => unsupported(),
+  receipt: async () => unsupported(),
+  cancel: async () => unsupported(),
+};

package/src/normalize.ts

@@ -0,0 +1,116 @@
+import type {
+  EcrFailure,
+  EcrFailureKind,
+  EcrInquiry,
+  EcrReceipt,
+  EcrResult,
+} from './types';
+
+type NativeRecord = Record<string, unknown>;
+
+const knownFailures = new Set<EcrFailureKind>([
+  'unreachable',
+  'timeout',
+  'malformed',
+  'connectionLost',
+  'unauthenticated',
+  'cancelled',
+  'unsupported',
+]);
+
+function record(value: unknown, label: string): NativeRecord {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`The native ECR host returned an invalid ${label}.`);
+  }
+  return value as NativeRecord;
+}
+
+function failure(value: unknown): EcrFailure {
+  const raw = record(value, 'failure');
+  const rawKind = String(raw.kind ?? 'malformed');
+  const kind = knownFailures.has(rawKind as EcrFailureKind)
+    ? (rawKind as EcrFailureKind)
+    : 'malformed';
+  return {
+    kind,
+    message: String(
+      raw.message ?? 'The native ECR host did not explain the failure.'
+    ),
+    outcomeIsUnknown: kind !== 'unreachable' && kind !== 'unsupported',
+  };
+}
+
+export function normalizeInquiry(value: unknown): EcrInquiry {
+  const raw = record(value, 'inquiry');
+  switch (raw.outcome) {
+    case 'found':
+    case 'notFound':
+      return raw as unknown as EcrInquiry;
+    case 'failed':
+      return { ...raw, failure: failure(raw.failure) } as EcrInquiry;
+    default:
+      throw new Error(
+        'The native ECR host returned an unknown inquiry outcome.'
+      );
+  }
+}
+
+export function normalizeReceipt(value: unknown): EcrReceipt {
+  const raw = record(value, 'receipt');
+  switch (raw.outcome) {
+    case 'ready':
+    case 'unavailable':
+      return raw as unknown as EcrReceipt;
+    case 'failed':
+      return { ...raw, failure: failure(raw.failure) } as EcrReceipt;
+    default:
+      throw new Error(
+        'The native ECR host returned an unknown receipt outcome.'
+      );
+  }
+}
+
+export function normalizeResult(value: unknown): EcrResult {
+  const raw = record(value, 'transaction result');
+  switch (raw.outcome) {
+    case 'approved':
+      return {
+        ...raw,
+        outcomeIsUnknown: false,
+        nextStep: 'NONE',
+      } as unknown as EcrResult;
+    case 'declined': {
+      const nextStep =
+        raw.nextStep === 'INQUIRE_BY_MERCHANT_REFERENCE'
+          ? 'INQUIRE_BY_MERCHANT_REFERENCE'
+          : 'NONE';
+      return {
+        ...raw,
+        nextStep,
+        outcomeIsUnknown:
+          raw.responseCode === '91' ||
+          nextStep === 'INQUIRE_BY_MERCHANT_REFERENCE',
+      } as unknown as EcrResult;
+    }
+    case 'failed': {
+      const recovered = raw.recovered
+        ? normalizeInquiry(raw.recovered)
+        : undefined;
+      const mappedFailure = failure(raw.failure);
+      const settled = recovered?.outcome === 'found';
+      const outcomeIsUnknown = mappedFailure.outcomeIsUnknown && !settled;
+      return {
+        ...raw,
+        failure: mappedFailure,
+        recovered,
+        settled,
+        outcomeIsUnknown,
+        nextStep: outcomeIsUnknown ? 'INQUIRE_BY_MERCHANT_REFERENCE' : 'NONE',
+      } as unknown as EcrResult;
+    }
+    default:
+      throw new Error(
+        'The native ECR host returned an unknown transaction outcome.'
+      );
+  }
+}

package/src/types.ts

@@ -0,0 +1,189 @@
+/**
+ * How the till reaches the terminal.
+ *
+ * `wifi` and `ethernet` open a TCP socket to the terminal's local IP.
+ * `webService` drives the terminal through the Amwal payment host over REST —
+ * no local network involved; it needs `merchantId`, `terminalId` and
+ * `environment` in the config instead of a host. `usbCable` and `bluetooth`
+ * are not handled by this library and answer with a typed `unsupported`
+ * failure without sending anything.
+ */
+export type EcrTransport =
+  'ethernet' | 'wifi' | 'bluetooth' | 'usbCable' | 'webService';
+
+/**
+ * Hub deployment for Web Service ECR. URLs are resolved inside the native
+ * SDKs; integrators pass only this name.
+ */
+export type EcrEnvironment = 'SIT' | 'UAT' | 'PROD';
+
+export interface EcrConfig {
+  ecrId?: string;
+  currencyCode?: string;
+  minorUnitDigits?: number;
+  port?: number;
+  connectTimeoutMs?: number;
+  responseTimeoutMs?: number;
+  probeTimeoutMs?: number;
+  secureHashKey?: string;
+  autoInquireOnFailure?: boolean;
+  /** Backend merchant ID — required for the `webService` transport. */
+  merchantId?: string;
+  /** Backend terminal ID — required for the `webService` transport. */
+  terminalId?: string;
+  /** Hub deployment for the `webService` transport. Defaults to `'SIT'`. */
+  environment?: EcrEnvironment;
+}
+
+export interface EcrTerminalOptions {
+  /**
+   * The terminal's IP address. Required for `wifi` and `ethernet`; ignored by
+   * `webService`, which addresses the terminal through the payment host.
+   */
+  host?: string;
+  serialNumber?: string;
+  transport?: EcrTransport;
+  config?: EcrConfig;
+}
+
+export type EcrNextStep = 'NONE' | 'INQUIRE_BY_MERCHANT_REFERENCE';
+
+export type EcrFailureKind =
+  | 'unreachable'
+  | 'timeout'
+  | 'malformed'
+  | 'connectionLost'
+  | 'unauthenticated'
+  | 'cancelled'
+  | 'unsupported';
+
+export interface EcrFailure {
+  kind: EcrFailureKind;
+  message: string;
+  outcomeIsUnknown: boolean;
+}
+
+export interface EcrApproved {
+  outcome: 'approved';
+  merchantReferenceId: string;
+  amount: string;
+  responseCode: string;
+  rrn: string;
+  authCode: string;
+  maskedPan: string;
+  partialApproval: boolean;
+  requestedAmount: string;
+  raw: string;
+  outcomeIsUnknown: false;
+  nextStep: 'NONE';
+}
+
+export interface EcrDeclined {
+  outcome: 'declined';
+  merchantReferenceId: string;
+  responseCode: string;
+  reason: string;
+  nextStep: EcrNextStep;
+  raw: string;
+  outcomeIsUnknown: boolean;
+}
+
+export interface EcrFailed {
+  outcome: 'failed';
+  merchantReferenceId: string;
+  failure: EcrFailure;
+  recovered?: EcrInquiry;
+  settled: boolean;
+  outcomeIsUnknown: boolean;
+  nextStep: EcrNextStep;
+}
+
+export type EcrResult = EcrApproved | EcrDeclined | EcrFailed;
+
+export interface EcrTransaction {
+  transactionId: string;
+  stan: string;
+  type: string;
+  status: string;
+  amount: string;
+  totalAmount: string;
+  currency: string;
+  transactionTime: string;
+  maskedPan: string;
+  cardHolderName: string;
+  rrn: string;
+  authCode: string;
+  batchId: string;
+  terminalId: string;
+  isRefunded: boolean;
+  canVoid: boolean;
+  canRefund: boolean;
+  partialApproval: boolean;
+  authorizedAmount: string;
+}
+
+export interface EcrInquiryFound {
+  outcome: 'found';
+  merchantReferenceId: string;
+  transaction: EcrTransaction;
+  raw: string;
+}
+
+export interface EcrInquiryNotFound {
+  outcome: 'notFound';
+  merchantReferenceId: string;
+  reason: string;
+  raw: string;
+}
+
+export interface EcrInquiryFailed {
+  outcome: 'failed';
+  merchantReferenceId: string;
+  failure: EcrFailure;
+}
+
+export type EcrInquiry =
+  EcrInquiryFound | EcrInquiryNotFound | EcrInquiryFailed;
+
+export interface EcrReceiptReady {
+  outcome: 'ready';
+  merchantReferenceId: string;
+  url: string;
+  raw: string;
+}
+
+export interface EcrReceiptUnavailable {
+  outcome: 'unavailable';
+  merchantReferenceId: string;
+  reason: string;
+  raw: string;
+}
+
+export interface EcrReceiptFailed {
+  outcome: 'failed';
+  merchantReferenceId: string;
+  failure: EcrFailure;
+}
+
+export type EcrReceipt =
+  EcrReceiptReady | EcrReceiptUnavailable | EcrReceiptFailed;
+
+export interface EcrReferenceOptions {
+  merchantReferenceId?: string;
+  operationId?: string;
+}
+
+export interface EcrOriginalTransactionOptions extends EcrReferenceOptions {
+  originalTerminalId?: string;
+}
+
+export interface EcrDatedTransactionOptions extends EcrOriginalTransactionOptions {
+  receiptNumber: string;
+  transactionDate: string;
+}
+
+export interface EcrRefundOptions extends EcrDatedTransactionOptions {}
+
+export interface EcrInquiryByReferenceOptions extends EcrOriginalTransactionOptions {
+  transactionDate?: string;
+}