react-native-amwal-ecr 0.1.0

package/android/src/main/java/com/amwalecr/AmwalEcrModule.kt

@@ -0,0 +1,325 @@
+package com.amwalecr
+
+import com.amwalpay.ecr.EcrConfig
+import com.amwalpay.ecr.EcrEnvironment
+import com.amwalpay.ecr.EcrLink
+import com.amwalpay.ecr.EcrLogger
+import com.amwalpay.ecr.EcrOpenedSession
+import com.amwalpay.ecr.EcrSessions
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.module.annotations.ReactModule
+import java.math.BigDecimal
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.atomic.AtomicBoolean
+import kotlin.time.Duration.Companion.milliseconds
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.CoroutineStart
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.launch
+
+@ReactModule(name = AmwalEcrModule.NAME)
+class AmwalEcrModule(reactContext: ReactApplicationContext) :
+  NativeAmwalEcrSpec(reactContext) {
+
+  private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main.immediate)
+  private val running = ConcurrentHashMap<String, RunningOperation>()
+
+  override fun isReachable(request: ReadableMap, promise: Promise) {
+    val call = parse(request, promise) ?: return
+    if (!call.isIpTransport) {
+      promise.resolve(false)
+      return
+    }
+    scope.launch {
+      try {
+        promise.resolve(call.session.probeReachability()?.reachable == true)
+      } catch (error: IllegalArgumentException) {
+        promise.reject(ECR_INVALID_ARGUMENT, error.message ?: "Invalid ECR arguments", error)
+      } catch (error: Exception) {
+        promise.reject(ECR_INTERNAL, error.message ?: "Reachability probe failed", error)
+      }
+    }
+  }
+
+  override fun sale(request: ReadableMap, promise: Promise) {
+    run(request, promise) { call ->
+      EcrMapping.result(
+        call.session.sale(
+          amount = call.requiredAmount(),
+          merchantReference = call.merchantReferenceId,
+        ),
+      )
+    }
+  }
+
+  override fun voidTransaction(request: ReadableMap, promise: Promise) {
+    run(request, promise) { call ->
+      EcrMapping.result(
+        call.session.void(
+          receiptNumber = call.requiredReceiptNumber("A void"),
+          originalTerminalId = call.originalTerminalId,
+          merchantReference = call.merchantReferenceId,
+        ),
+      )
+    }
+  }
+
+  override fun refund(request: ReadableMap, promise: Promise) {
+    run(request, promise) { call ->
+      EcrMapping.result(
+        call.session.refund(
+          amount = call.requiredAmount(),
+          receiptNumber = call.requiredReceiptNumber("A refund"),
+          transactionDate = call.transactionDate,
+          originalTerminalId = call.originalTerminalId,
+          merchantReference = call.merchantReferenceId,
+        ),
+      )
+    }
+  }
+
+  override fun inquire(request: ReadableMap, promise: Promise) {
+    run(request, promise) { call ->
+      EcrMapping.inquiry(
+        call.session.inquire(
+          receiptNumber = call.requiredReceiptNumber("An inquiry"),
+          transactionDate = call.transactionDate,
+          originalTerminalId = call.originalTerminalId,
+        ),
+      )
+    }
+  }
+
+  override fun inquireByReference(request: ReadableMap, promise: Promise) {
+    run(request, promise) { call ->
+      EcrMapping.inquiry(
+        call.session.inquireByReference(
+          originalReference = call.requiredOriginalReference(),
+          transactionDate = call.transactionDate,
+          originalTerminalId = call.originalTerminalId,
+          merchantReference = call.merchantReferenceId,
+        ),
+      )
+    }
+  }
+
+  override fun receipt(request: ReadableMap, promise: Promise) {
+    run(request, promise) { call ->
+      EcrMapping.receipt(
+        call.session.receipt(
+          receiptNumber = call.requiredReceiptNumber("A receipt"),
+          transactionDate = call.transactionDate,
+          originalTerminalId = call.originalTerminalId,
+        ),
+      )
+    }
+  }
+
+  override fun cancel(operationId: String, promise: Promise) {
+    val operation = running.remove(operationId)
+    if (operation == null) {
+      promise.resolve(false)
+      return
+    }
+
+    operation.reply.resolve(
+      EcrMapping.failedResult(
+        merchantReferenceId = operation.merchantReferenceId,
+        kind = EcrMapping.CANCELLED,
+        message = CANCELLED_MESSAGE,
+      ),
+    )
+    operation.job.cancel()
+    promise.resolve(true)
+  }
+
+  override fun invalidate() {
+    running.values.forEach { operation ->
+      operation.reply.resolve(
+        EcrMapping.failedResult(
+          merchantReferenceId = operation.merchantReferenceId,
+          kind = EcrMapping.CANCELLED,
+          message = "The React Native host was invalidated while the terminal had the request. " +
+            "The transaction may still have completed — inquire before retrying.",
+        ),
+      )
+      operation.job.cancel()
+    }
+    running.clear()
+    scope.cancel()
+    super.invalidate()
+  }
+
+  private fun run(
+    request: ReadableMap,
+    promise: Promise,
+    block: suspend (Call) -> Any,
+  ) {
+    val call = parse(request, promise) ?: return
+    val reply = OneShotPromise(promise)
+
+    if (!call.isSupportedTransport) {
+      reply.resolve(
+        EcrMapping.failedResult(
+          merchantReferenceId = "",
+          kind = EcrMapping.UNSUPPORTED,
+          message = "This library drives a terminal over ethernet, wifi, or the Web Service " +
+            "REST path. Transport '${call.transport}' is not handled, so nothing was sent.",
+        ),
+      )
+      return
+    }
+
+    lateinit var operation: RunningOperation
+    val job = scope.launch(start = CoroutineStart.LAZY) {
+      try {
+        reply.resolve(block(call))
+      } catch (error: IllegalArgumentException) {
+        reply.reject(ECR_INVALID_ARGUMENT, error.message ?: "Invalid ECR arguments", error)
+      } catch (error: Exception) {
+        reply.reject(ECR_INTERNAL, error.message ?: "Native ECR operation failed", error)
+      } finally {
+        running.remove(call.operationId, operation)
+      }
+    }
+    operation = RunningOperation(job, reply, call.merchantReferenceId)
+
+    if (running.putIfAbsent(call.operationId, operation) != null) {
+      reply.reject(
+        ECR_INVALID_ARGUMENT,
+        "operationId '${call.operationId}' is already running",
+        null,
+      )
+      return
+    }
+    job.start()
+  }
+
+  private fun parse(request: ReadableMap, promise: Promise): Call? = try {
+    Call(request)
+  } catch (error: IllegalArgumentException) {
+    promise.reject(ECR_INVALID_ARGUMENT, error.message ?: "Invalid ECR arguments", error)
+    null
+  } catch (error: Exception) {
+    promise.reject(ECR_INTERNAL, error.message ?: "Could not read ECR arguments", error)
+    null
+  }
+
+  private data class RunningOperation(
+    val job: Job,
+    val reply: OneShotPromise,
+    val merchantReferenceId: String,
+  )
+
+  private class OneShotPromise(private val promise: Promise) {
+    private val answered = AtomicBoolean(false)
+
+    fun resolve(value: Any?) {
+      if (answered.compareAndSet(false, true)) promise.resolve(value)
+    }
+
+    fun reject(code: String, message: String, error: Throwable?) {
+      if (answered.compareAndSet(false, true)) promise.reject(code, message, error)
+    }
+  }
+
+  private class Call(private val raw: ReadableMap) {
+    val operationId = raw.requiredString("operationId")
+    val host = raw.optionalString("host")
+    val serialNumber = raw.optionalString("serialNumber")
+    val transport = raw.optionalString("transport").ifEmpty { "wifi" }
+    val transactionDate = raw.optionalString("transactionDate")
+    val originalTerminalId = raw.optionalString("originalTerminalId")
+    val merchantReferenceId = raw.optionalString("merchantReferenceId")
+    private val config = raw.config()
+
+    val isIpTransport get() = transport == "ethernet" || transport == "wifi"
+    val isWebService get() = transport == "webService" || transport == "web_service"
+    val isSupportedTransport get() = isIpTransport || isWebService
+
+    /**
+     * The SDK session for this call's transport: TCP for ethernet/wifi, the
+     * hosted REST path for webService. Built lazily so an unsupported
+     * transport is answered as a typed failure before any session exists.
+     */
+    val session: EcrOpenedSession by lazy {
+      val link = if (isWebService) {
+        EcrLink.WebService(
+          merchantId = config.merchantId,
+          terminalId = config.terminalId,
+        )
+      } else {
+        EcrLink.Lan(host = host, port = config.port)
+      }
+      val plan = EcrSessions.plan(link = link, config = config)
+      require(plan.isReady) { plan.issues.joinToString("; ") }
+      EcrSessions.open(
+        terminalSerial = serialNumber,
+        plan = plan,
+        logger = EcrLogger.None,
+      )
+    }
+
+    fun requiredAmount(): BigDecimal {
+      val text = raw.requiredString("amount")
+      return try {
+        BigDecimal(text)
+      } catch (error: NumberFormatException) {
+        throw IllegalArgumentException("'$text' is not a decimal amount", error)
+      }
+    }
+
+    fun requiredReceiptNumber(operation: String): String =
+      raw.optionalString("receiptNumber").ifBlank {
+        throw IllegalArgumentException("$operation needs the original receipt number")
+      }
+
+    fun requiredOriginalReference(): String =
+      raw.optionalString("originalMerchantReference").ifBlank {
+        throw IllegalArgumentException("An inquiry by reference needs the original reference")
+      }
+  }
+
+  companion object {
+    const val NAME = NativeAmwalEcrSpec.NAME
+    private const val ECR_INVALID_ARGUMENT = "ECR_INVALID_ARGUMENT"
+    private const val ECR_INTERNAL = "ECR_INTERNAL"
+    private const val CANCELLED_MESSAGE =
+      "The caller cancelled while the terminal had the request. " +
+        "The transaction may still have completed — inquire before retrying."
+  }
+}
+
+private fun ReadableMap.requiredString(key: String): String {
+  val value = optionalString(key).trim()
+  require(value.isNotEmpty()) { "'$key' is required and was missing" }
+  return value
+}
+
+private fun ReadableMap.optionalString(key: String): String =
+  if (hasKey(key) && !isNull(key)) getString(key).orEmpty() else ""
+
+private fun ReadableMap.config(): EcrConfig {
+  val source = if (hasKey("config") && !isNull("config")) getMap("config") else null
+  if (source == null) return EcrConfig()
+
+  return EcrConfig(
+    ecrId = source.optionalString("ecrId").ifEmpty { "ECR01" },
+    currencyCode = source.optionalString("currencyCode").ifEmpty { "512" },
+    minorUnitDigits = if (source.hasKey("minorUnitDigits")) source.getInt("minorUnitDigits") else 3,
+    port = if (source.hasKey("port")) source.getInt("port") else EcrConfig.DEFAULT_PORT,
+    connectTimeout = (if (source.hasKey("connectTimeoutMs")) source.getDouble("connectTimeoutMs").toLong() else 10_000L).milliseconds,
+    responseTimeout = (if (source.hasKey("responseTimeoutMs")) source.getDouble("responseTimeoutMs").toLong() else 120_000L).milliseconds,
+    probeTimeout = (if (source.hasKey("probeTimeoutMs")) source.getDouble("probeTimeoutMs").toLong() else 3_000L).milliseconds,
+    secureHashKey = source.optionalString("secureHashKey"),
+    autoInquireOnFailure = if (source.hasKey("autoInquireOnFailure")) source.getBoolean("autoInquireOnFailure") else true,
+    merchantId = source.optionalString("merchantId"),
+    terminalId = source.optionalString("terminalId"),
+    environment = EcrEnvironment.fromName(source.optionalString("environment")),
+  )
+}

package/android/src/main/java/com/amwalecr/AmwalEcrPackage.kt

@@ -0,0 +1,31 @@
+package com.amwalecr
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+import java.util.HashMap
+
+class AmwalEcrPackage : BaseReactPackage() {
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+    return if (name == AmwalEcrModule.NAME) {
+      AmwalEcrModule(reactContext)
+    } else {
+      null
+    }
+  }
+
+  override fun getReactModuleInfoProvider() = ReactModuleInfoProvider {
+    mapOf(
+      AmwalEcrModule.NAME to ReactModuleInfo(
+        name = AmwalEcrModule.NAME,
+        className = AmwalEcrModule.NAME,
+        canOverrideExistingModule = false,
+        needsEagerInit = false,
+        isCxxModule = false,
+        isTurboModule = true
+      )
+    )
+  }
+}

package/android/src/main/java/com/amwalecr/EcrMapping.kt

@@ -0,0 +1,135 @@
+package com.amwalecr
+
+import com.amwalpay.ecr.EcrInquiry
+import com.amwalpay.ecr.EcrReceipt
+import com.amwalpay.ecr.EcrResult
+import com.amwalpay.ecr.EcrTransaction
+import com.amwalpay.ecr.Failure
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+
+internal object EcrMapping {
+  const val CANCELLED = "cancelled"
+  const val UNSUPPORTED = "unsupported"
+
+  fun result(result: EcrResult): WritableMap = when (result) {
+    is EcrResult.Approved -> Arguments.createMap().apply {
+      putString("outcome", "approved")
+      putString("merchantReferenceId", result.merchantReference)
+      putString("amount", result.amount)
+      putString("responseCode", result.responseCode)
+      putString("rrn", result.rrn)
+      putString("authCode", result.authCode)
+      putString("maskedPan", result.maskedPan)
+      putBoolean("partialApproval", result.partialApproval)
+      putString("requestedAmount", result.requestedAmount)
+      putString("raw", result.raw)
+    }
+
+    is EcrResult.Declined -> Arguments.createMap().apply {
+      putString("outcome", "declined")
+      putString("merchantReferenceId", result.merchantReference)
+      putString("responseCode", result.responseCode)
+      putString("reason", result.reason)
+      putString("nextStep", result.nextStep.name)
+      putString("raw", result.raw)
+    }
+
+    is EcrResult.Failed -> Arguments.createMap().apply {
+      putString("outcome", "failed")
+      putString("merchantReferenceId", result.merchantReference)
+      putMap("failure", failure(result.failure))
+      result.recovered?.let { putMap("recovered", inquiry(it)) }
+    }
+  }
+
+  fun inquiry(inquiry: EcrInquiry): WritableMap = when (inquiry) {
+    is EcrInquiry.Found -> Arguments.createMap().apply {
+      putString("outcome", "found")
+      putString("merchantReferenceId", inquiry.merchantReference)
+      putMap("transaction", transaction(inquiry.transaction))
+      putString("raw", inquiry.raw)
+    }
+
+    is EcrInquiry.NotFound -> Arguments.createMap().apply {
+      putString("outcome", "notFound")
+      putString("merchantReferenceId", inquiry.merchantReference)
+      putString("reason", inquiry.reason)
+      putString("raw", inquiry.raw)
+    }
+
+    is EcrInquiry.Failed -> Arguments.createMap().apply {
+      putString("outcome", "failed")
+      putString("merchantReferenceId", inquiry.merchantReference)
+      putMap("failure", failure(inquiry.failure))
+    }
+  }
+
+  fun receipt(receipt: EcrReceipt): WritableMap = when (receipt) {
+    is EcrReceipt.Ready -> Arguments.createMap().apply {
+      putString("outcome", "ready")
+      putString("merchantReferenceId", receipt.merchantReference)
+      putString("url", receipt.url)
+      putString("raw", receipt.raw)
+    }
+
+    is EcrReceipt.Unavailable -> Arguments.createMap().apply {
+      putString("outcome", "unavailable")
+      putString("merchantReferenceId", receipt.merchantReference)
+      putString("reason", receipt.reason)
+      putString("raw", receipt.raw)
+    }
+
+    is EcrReceipt.Failed -> Arguments.createMap().apply {
+      putString("outcome", "failed")
+      putString("merchantReferenceId", receipt.merchantReference)
+      putMap("failure", failure(receipt.failure))
+    }
+  }
+
+  fun failedResult(
+    merchantReferenceId: String,
+    kind: String,
+    message: String,
+  ): WritableMap = Arguments.createMap().apply {
+    putString("outcome", "failed")
+    putString("merchantReferenceId", merchantReferenceId)
+    putMap("failure", Arguments.createMap().apply {
+      putString("kind", kind)
+      putString("message", message)
+    })
+  }
+
+  private fun transaction(value: EcrTransaction): WritableMap = Arguments.createMap().apply {
+    putString("transactionId", value.transactionId)
+    putString("stan", value.stan)
+    putString("type", value.type)
+    putString("status", value.status)
+    putString("amount", value.amount)
+    putString("totalAmount", value.totalAmount)
+    putString("currency", value.currency)
+    putString("transactionTime", value.transactionTime)
+    putString("maskedPan", value.maskedPan)
+    putString("cardHolderName", value.cardHolderName)
+    putString("rrn", value.rrn)
+    putString("authCode", value.authCode)
+    putString("batchId", value.batchId)
+    putString("terminalId", value.terminalId)
+    putBoolean("isRefunded", value.isRefunded)
+    putBoolean("canVoid", value.canVoid)
+    putBoolean("canRefund", value.canRefund)
+    putBoolean("partialApproval", value.partialApproval)
+    putString("authorizedAmount", value.authorizedAmount)
+  }
+
+  private fun failure(value: Failure): WritableMap = Arguments.createMap().apply {
+    putString("kind", when (value) {
+      is Failure.Unreachable -> "unreachable"
+      is Failure.Timeout -> "timeout"
+      is Failure.Malformed -> "malformed"
+      is Failure.ConnectionLost -> "connectionLost"
+      is Failure.Unauthenticated -> "unauthenticated"
+    })
+    putString("message", value.message)
+  }
+}

package/docs/compatibility.md

@@ -0,0 +1,22 @@
+# Compatibility
+
+| Layer | Version or minimum |
+|---|---|
+| `react-native-amwal-ecr` | 0.1.0 |
+| React Native | 0.87.1 development baseline; peer dependency accepts supported host versions |
+| Android provider | `com.amwal-pay:ecr-sdk:1.0.5` exactly |
+| Android | API 24+, Java 17, compile SDK 36 |
+| iOS provider | `AmwalECR ~> 0.2.1` |
+| iOS | 15.1+ with the current React Native baseline |
+| Protocol | ECR protocol version 1 |
+
+Android is pinned exactly because changing how a payment outcome is interpreted
+must be deliberate. iOS uses the provider's compatible patch line so CocoaPods
+can resolve a host application that also uses `AmwalECR` directly.
+
+The two provider versions must move together and only after their cross-platform
+contract fixtures pass. `ethernet`, `wifi` and `webService` are supported —
+the first two over TCP on the local network, `webService` through the Amwal
+payment host over REST (`merchantId`, `terminalId` and `environment` in the
+config select the terminal; receipt fetch stays local-only). `bluetooth` and
+`usbCable` are reported as unsupported before anything is sent.

package/ios/AmwalEcr.h

@@ -0,0 +1,4 @@
+#import <AmwalEcrSpec/AmwalEcrSpec.h>
+
+@interface AmwalEcr : NSObject <NativeAmwalEcrSpec>
+@end

package/ios/AmwalEcr.mm

@@ -0,0 +1,121 @@
+#import "AmwalEcr.h"
+
+@interface AmwalEcrImpl : NSObject
+- (void)isReachable:(NSDictionary *)request
+           resolver:(RCTPromiseResolveBlock)resolve
+           rejecter:(RCTPromiseRejectBlock)reject;
+- (void)sale:(NSDictionary *)request
+     resolver:(RCTPromiseResolveBlock)resolve
+     rejecter:(RCTPromiseRejectBlock)reject;
+- (void)voidTransaction:(NSDictionary *)request
+                resolver:(RCTPromiseResolveBlock)resolve
+                rejecter:(RCTPromiseRejectBlock)reject;
+- (void)refund:(NSDictionary *)request
+       resolver:(RCTPromiseResolveBlock)resolve
+       rejecter:(RCTPromiseRejectBlock)reject;
+- (void)inquire:(NSDictionary *)request
+        resolver:(RCTPromiseResolveBlock)resolve
+        rejecter:(RCTPromiseRejectBlock)reject;
+- (void)inquireByReference:(NSDictionary *)request
+                   resolver:(RCTPromiseResolveBlock)resolve
+                   rejecter:(RCTPromiseRejectBlock)reject;
+- (void)receipt:(NSDictionary *)request
+        resolver:(RCTPromiseResolveBlock)resolve
+        rejecter:(RCTPromiseRejectBlock)reject;
+- (void)cancel:(NSString *)operationId
+       resolver:(RCTPromiseResolveBlock)resolve
+       rejecter:(RCTPromiseRejectBlock)reject;
+- (void)invalidate;
+@end
+
+@implementation AmwalEcr {
+  AmwalEcrImpl *_implementation;
+}
+
+- (instancetype)init
+{
+  self = [super init];
+  if (self) {
+    _implementation = [AmwalEcrImpl new];
+  }
+  return self;
+}
+
+- (void)isReachable:(NSDictionary *)request
+             resolve:(RCTPromiseResolveBlock)resolve
+              reject:(RCTPromiseRejectBlock)reject
+{
+  [_implementation isReachable:request resolver:resolve rejecter:reject];
+}
+
+- (void)sale:(NSDictionary *)request
+       resolve:(RCTPromiseResolveBlock)resolve
+        reject:(RCTPromiseRejectBlock)reject
+{
+  [_implementation sale:request resolver:resolve rejecter:reject];
+}
+
+- (void)voidTransaction:(NSDictionary *)request
+                  resolve:(RCTPromiseResolveBlock)resolve
+                   reject:(RCTPromiseRejectBlock)reject
+{
+  [_implementation voidTransaction:request resolver:resolve rejecter:reject];
+}
+
+- (void)refund:(NSDictionary *)request
+         resolve:(RCTPromiseResolveBlock)resolve
+          reject:(RCTPromiseRejectBlock)reject
+{
+  [_implementation refund:request resolver:resolve rejecter:reject];
+}
+
+- (void)inquire:(NSDictionary *)request
+          resolve:(RCTPromiseResolveBlock)resolve
+           reject:(RCTPromiseRejectBlock)reject
+{
+  [_implementation inquire:request resolver:resolve rejecter:reject];
+}
+
+- (void)inquireByReference:(NSDictionary *)request
+                     resolve:(RCTPromiseResolveBlock)resolve
+                      reject:(RCTPromiseRejectBlock)reject
+{
+  [_implementation inquireByReference:request resolver:resolve rejecter:reject];
+}
+
+- (void)receipt:(NSDictionary *)request
+          resolve:(RCTPromiseResolveBlock)resolve
+           reject:(RCTPromiseRejectBlock)reject
+{
+  [_implementation receipt:request resolver:resolve rejecter:reject];
+}
+
+- (void)cancel:(NSString *)operationId
+         resolve:(RCTPromiseResolveBlock)resolve
+          reject:(RCTPromiseRejectBlock)reject
+{
+  [_implementation cancel:operationId resolver:resolve rejecter:reject];
+}
+
+- (void)invalidate
+{
+  [_implementation invalidate];
+}
+
+- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
+    (const facebook::react::ObjCTurboModule::InitParams &)params
+{
+  return std::make_shared<facebook::react::NativeAmwalEcrSpecJSI>(params);
+}
+
++ (NSString *)moduleName
+{
+  return @"AmwalEcr";
+}
+
++ (BOOL)requiresMainQueueSetup
+{
+  return NO;
+}
+
+@end