react-native-amwal-ecr 0.1.0

package/lib/typescript/src/types.d.ts

@@ -0,0 +1,157 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,153 @@
+{
+  "name": "react-native-amwal-ecr",
+  "version": "0.1.0",
+  "description": "React Native bridge for the Amwal ECR SDK on Android and iOS.",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "react-native-amwal-ecr-source": "./src/index.tsx",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "cpp",
+    "docs",
+    "CHANGELOG.md",
+    "LICENSE",
+    "*.podspec",
+    "react-native.config.js",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "example": "yarn workspace react-native-amwal-ecr-example",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
+    "prepare": "bob build",
+    "test": "jest",
+    "test:ci": "jest --ci --runInBand --coverage",
+    "typecheck": "tsc",
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "verify": "yarn lint && yarn typecheck && yarn test:ci && yarn prepare && npm pack --dry-run"
+  },
+  "keywords": [
+    "react-native",
+    "ios",
+    "android",
+    "ecr",
+    "pos",
+    "payments",
+    "terminal"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amwal-pay/amwal-ecr-rn.git"
+  },
+  "author": "Amwal Pay <support@amwal-pay.com> (https://amwal-pay.com)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/amwal-pay/amwal-ecr-rn/issues"
+  },
+  "homepage": "https://github.com/amwal-pay/amwal-ecr-rn#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^2.1.0",
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "^10.0.1",
+    "@react-native/babel-preset": "0.87.1",
+    "@react-native/eslint-config": "0.85.0",
+    "@react-native/jest-preset": "0.87.1",
+    "@types/jest": "^30.0.0",
+    "@types/react": "^19.2.0",
+    "del-cli": "^7.0.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-ft-flow": "^3.0.11",
+    "eslint-plugin-prettier": "^5.5.6",
+    "jest": "^30.2.0",
+    "prettier": "^3.8.3",
+    "react": "19.2.3",
+    "react-native": "0.87.1",
+    "react-native-builder-bob": "^0.43.0",
+    "turbo": "^2.9.16",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  },
+  "workspaces": [
+    "example"
+  ],
+  "packageManager": "yarn@4.11.0",
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "codegenConfig": {
+    "name": "AmwalEcrSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "com.amwalecr"
+    }
+  },
+  "jest": {
+    "preset": "@react-native/jest-preset",
+    "watchman": false,
+    "modulePathIgnorePatterns": [
+      "<rootDir>/example/node_modules",
+      "<rootDir>/lib/"
+    ],
+    "collectCoverageFrom": [
+      "src/**/*.{ts,tsx}",
+      "!src/NativeAmwalEcr.ts",
+      "!src/**/*.native.ts"
+    ]
+  },
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "create-react-native-library": {
+    "type": "turbo-module",
+    "languages": "kotlin-objc",
+    "tools": [
+      "eslint"
+    ],
+    "version": "0.63.0"
+  }
+}

package/src/EcrOperation.ts

@@ -0,0 +1,25 @@
+export class EcrOperation<T> {
+  readonly operationId: string;
+  readonly result: Promise<T>;
+  private readonly onCancel: (operationId: string) => Promise<boolean>;
+  private cancelRequested = false;
+
+  constructor(
+    operationId: string,
+    result: Promise<T>,
+    onCancel: (operationId: string) => Promise<boolean>
+  ) {
+    this.operationId = operationId;
+    this.result = result;
+    this.onCancel = onCancel;
+  }
+
+  get isCancelRequested(): boolean {
+    return this.cancelRequested;
+  }
+
+  cancel(): Promise<boolean> {
+    this.cancelRequested = true;
+    return this.onCancel(this.operationId);
+  }
+}

package/src/EcrTerminal.ts

@@ -0,0 +1,344 @@
+import { EcrOperation } from './EcrOperation';
+import { nativeEcr } from './native';
+import {
+  normalizeInquiry,
+  normalizeReceipt,
+  normalizeResult,
+} from './normalize';
+import type {
+  EcrConfig,
+  EcrDatedTransactionOptions,
+  EcrEnvironment,
+  EcrInquiry,
+  EcrInquiryByReferenceOptions,
+  EcrOriginalTransactionOptions,
+  EcrReceipt,
+  EcrReferenceOptions,
+  EcrRefundOptions,
+  EcrResult,
+  EcrTerminalOptions,
+  EcrTransport,
+} from './types';
+
+const DEFAULT_CONFIG: Required<EcrConfig> = {
+  ecrId: 'ECR01',
+  currencyCode: '512',
+  minorUnitDigits: 3,
+  port: 9100,
+  connectTimeoutMs: 10_000,
+  responseTimeoutMs: 120_000,
+  probeTimeoutMs: 3_000,
+  secureHashKey: '',
+  autoInquireOnFailure: true,
+  merchantId: '',
+  terminalId: '',
+  environment: 'SIT',
+};
+
+const ENVIRONMENTS: readonly EcrEnvironment[] = ['SIT', 'UAT', 'PROD'];
+
+let operationSequence = 0;
+
+function newOperationId(): string {
+  operationSequence = (operationSequence + 1) % Number.MAX_SAFE_INTEGER;
+  return `ecr-${Date.now().toString(36)}-${operationSequence.toString(36)}-${Math.random()
+    .toString(36)
+    .slice(2, 10)}`;
+}
+
+function requireText(value: string, label: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new TypeError(`${label} is required.`);
+  }
+  return trimmed;
+}
+
+function requireAmount(amount: string): string {
+  const trimmed = amount.trim();
+  if (!/^\d+(\.\d+)?$/.test(trimmed)) {
+    throw new TypeError(
+      `"${amount}" is not a plain decimal amount. Use a string such as "1.234".`
+    );
+  }
+  return trimmed;
+}
+
+function requireDate(value: string, required: boolean): string {
+  const trimmed = value.trim();
+  if (!trimmed && !required) return '';
+  if (!/^\d{8}$/.test(trimmed)) {
+    throw new TypeError(
+      'transactionDate must use yyyyMMdd, for example 20260902.'
+    );
+  }
+  return trimmed;
+}
+
+function requireReference(value: string | undefined, label: string): string {
+  const trimmed = value?.trim() ?? '';
+  if (!trimmed) return '';
+  if (trimmed.length > 32 || /[\s&=]/.test(trimmed)) {
+    throw new TypeError(
+      `${label} must be at most 32 characters and cannot contain whitespace, "&", or "=".`
+    );
+  }
+  return trimmed;
+}
+
+function positiveInteger(value: number, label: string): number {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new TypeError(`${label} must be a positive whole number.`);
+  }
+  return value;
+}
+
+function normalizeConfig(config: EcrConfig = {}): Required<EcrConfig> {
+  const normalized = { ...DEFAULT_CONFIG, ...config };
+  if (normalized.minorUnitDigits < 0 || normalized.minorUnitDigits > 4) {
+    throw new TypeError('minorUnitDigits must be between 0 and 4.');
+  }
+  if (normalized.port < 1 || normalized.port > 65_535) {
+    throw new TypeError('port must be between 1 and 65535.');
+  }
+  positiveInteger(normalized.connectTimeoutMs, 'connectTimeoutMs');
+  positiveInteger(normalized.responseTimeoutMs, 'responseTimeoutMs');
+  positiveInteger(normalized.probeTimeoutMs, 'probeTimeoutMs');
+  if (
+    normalized.secureHashKey &&
+    (normalized.secureHashKey.length < 16 ||
+      normalized.secureHashKey.length % 2 !== 0 ||
+      !/^[0-9a-fA-F]+$/.test(normalized.secureHashKey))
+  ) {
+    throw new TypeError(
+      'secureHashKey must be an even-length hexadecimal string of at least 16 characters, or empty.'
+    );
+  }
+  const environment = String(normalized.environment).toUpperCase();
+  if (!ENVIRONMENTS.includes(environment as EcrEnvironment)) {
+    throw new TypeError(
+      `environment must be one of ${ENVIRONMENTS.join(', ')}.`
+    );
+  }
+  normalized.environment = environment as EcrEnvironment;
+  return normalized;
+}
+
+type NativeRequest = Record<string, unknown>;
+
+/**
+ * One Amwal POS terminal reachable from the mobile device's local network.
+ *
+ * Amounts are decimal strings, never JavaScript numbers. A failed exchange is
+ * not a decline: when `outcomeIsUnknown` is true, inquire by the same merchant
+ * reference before considering another money-moving request.
+ */
+export class EcrTerminal {
+  readonly host: string;
+  readonly serialNumber: string;
+  readonly transport: EcrTransport;
+  readonly config: Required<EcrConfig>;
+
+  constructor(options: EcrTerminalOptions) {
+    this.serialNumber = options.serialNumber?.trim() ?? '';
+    this.transport = options.transport ?? 'wifi';
+    this.config = normalizeConfig(options.config);
+    if (this.transport === 'webService') {
+      // The payment host addresses the terminal; there is no IP to dial.
+      this.host = options.host?.trim() ?? '';
+      requireText(this.config.merchantId, 'config.merchantId');
+      requireText(this.config.terminalId, 'config.terminalId');
+    } else {
+      this.host = requireText(options.host ?? '', 'host');
+    }
+  }
+
+  isReachable(): Promise<boolean> {
+    if (!this.isIpTransport) return Promise.resolve(false);
+    return nativeEcr.isReachable(this.request(newOperationId()));
+  }
+
+  sale(amount: string, options: EcrReferenceOptions = {}): Promise<EcrResult> {
+    return this.startSale(amount, options).result;
+  }
+
+  startSale(
+    amount: string,
+    options: EcrReferenceOptions = {}
+  ): EcrOperation<EcrResult> {
+    return this.startResult('sale', {
+      amount: requireAmount(amount),
+      merchantReferenceId: requireReference(
+        options.merchantReferenceId,
+        'merchantReferenceId'
+      ),
+      operationId: options.operationId,
+    });
+  }
+
+  voidTransaction(
+    receiptNumber: string,
+    options: EcrOriginalTransactionOptions = {}
+  ): Promise<EcrResult> {
+    return this.startVoid(receiptNumber, options).result;
+  }
+
+  startVoid(
+    receiptNumber: string,
+    options: EcrOriginalTransactionOptions = {}
+  ): EcrOperation<EcrResult> {
+    return this.startResult('voidTransaction', {
+      receiptNumber: requireText(receiptNumber, 'receiptNumber'),
+      originalTerminalId: options.originalTerminalId?.trim() ?? '',
+      merchantReferenceId: requireReference(
+        options.merchantReferenceId,
+        'merchantReferenceId'
+      ),
+      operationId: options.operationId,
+    });
+  }
+
+  refund(amount: string, options: EcrRefundOptions): Promise<EcrResult> {
+    return this.startRefund(amount, options).result;
+  }
+
+  startRefund(
+    amount: string,
+    options: EcrRefundOptions
+  ): EcrOperation<EcrResult> {
+    return this.startResult('refund', {
+      amount: requireAmount(amount),
+      receiptNumber: requireText(options.receiptNumber, 'receiptNumber'),
+      transactionDate: requireDate(options.transactionDate, true),
+      originalTerminalId: options.originalTerminalId?.trim() ?? '',
+      merchantReferenceId: requireReference(
+        options.merchantReferenceId,
+        'merchantReferenceId'
+      ),
+      operationId: options.operationId,
+    });
+  }
+
+  inquire(options: EcrDatedTransactionOptions): Promise<EcrInquiry> {
+    return this.startInquire(options).result;
+  }
+
+  startInquire(options: EcrDatedTransactionOptions): EcrOperation<EcrInquiry> {
+    return this.startOperation(
+      'inquire',
+      {
+        receiptNumber: requireText(options.receiptNumber, 'receiptNumber'),
+        transactionDate: requireDate(options.transactionDate, true),
+        originalTerminalId: options.originalTerminalId?.trim() ?? '',
+        merchantReferenceId: requireReference(
+          options.merchantReferenceId,
+          'merchantReferenceId'
+        ),
+        operationId: options.operationId,
+      },
+      normalizeInquiry
+    );
+  }
+
+  inquireByReference(
+    originalMerchantReference: string,
+    options: EcrInquiryByReferenceOptions = {}
+  ): Promise<EcrInquiry> {
+    return this.startInquireByReference(originalMerchantReference, options)
+      .result;
+  }
+
+  startInquireByReference(
+    originalMerchantReference: string,
+    options: EcrInquiryByReferenceOptions = {}
+  ): EcrOperation<EcrInquiry> {
+    const originalReference = requireReference(
+      originalMerchantReference,
+      'originalMerchantReference'
+    );
+    requireText(originalReference, 'originalMerchantReference');
+    return this.startOperation(
+      'inquireByReference',
+      {
+        originalMerchantReference: originalReference,
+        transactionDate: requireDate(options.transactionDate ?? '', false),
+        originalTerminalId: options.originalTerminalId?.trim() ?? '',
+        merchantReferenceId: requireReference(
+          options.merchantReferenceId,
+          'merchantReferenceId'
+        ),
+        operationId: options.operationId,
+      },
+      normalizeInquiry
+    );
+  }
+
+  receipt(options: EcrDatedTransactionOptions): Promise<EcrReceipt> {
+    return this.startReceipt(options).result;
+  }
+
+  startReceipt(options: EcrDatedTransactionOptions): EcrOperation<EcrReceipt> {
+    return this.startOperation(
+      'receipt',
+      {
+        receiptNumber: requireText(options.receiptNumber, 'receiptNumber'),
+        transactionDate: requireDate(options.transactionDate, true),
+        originalTerminalId: options.originalTerminalId?.trim() ?? '',
+        merchantReferenceId: requireReference(
+          options.merchantReferenceId,
+          'merchantReferenceId'
+        ),
+        operationId: options.operationId,
+      },
+      normalizeReceipt
+    );
+  }
+
+  private get isIpTransport(): boolean {
+    return this.transport === 'ethernet' || this.transport === 'wifi';
+  }
+
+  private request(
+    operationId: string,
+    values: NativeRequest = {}
+  ): NativeRequest {
+    return {
+      operationId: requireText(operationId, 'operationId'),
+      host: this.host,
+      serialNumber: this.serialNumber,
+      transport: this.transport,
+      config: this.config,
+      ...values,
+    };
+  }
+
+  private startResult(
+    method: 'sale' | 'voidTransaction' | 'refund',
+    values: NativeRequest
+  ): EcrOperation<EcrResult> {
+    return this.startOperation(method, values, normalizeResult);
+  }
+
+  private startOperation<T>(
+    method:
+      | 'sale'
+      | 'voidTransaction'
+      | 'refund'
+      | 'inquire'
+      | 'inquireByReference'
+      | 'receipt',
+    values: NativeRequest,
+    normalize: (value: unknown) => T
+  ): EcrOperation<T> {
+    const suppliedId = values.operationId;
+    const operationId =
+      typeof suppliedId === 'string' && suppliedId.trim()
+        ? suppliedId.trim()
+        : newOperationId();
+    const requestValues = { ...values };
+    delete requestValues.operationId;
+    const request = this.request(operationId, requestValues);
+    const result = nativeEcr[method](request).then(normalize);
+    return new EcrOperation(operationId, result, (id) => nativeEcr.cancel(id));
+  }
+}