@fire-spark/payments-medianet-client 0.0.0-stage → 0.13.0

package/android/build.gradle

@@ -0,0 +1,20 @@
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'dev.firespark.payments.medianet'
+version = '0.1.0'
+
+android {
+  namespace "dev.firespark.payments.medianet"
+  defaultConfig {
+    versionCode 1
+    versionName "0.1.0"
+  }
+}
+
+dependencies {
+  // The app module ships the JAR (copied by the config plugin); this module only compiles against it.
+  compileOnly files("${rootProject.projectDir}/app/libs/CajaPinPadLibrary_V3.jar")
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.INTERNET" />
+</manifest>

package/android/src/main/java/dev/firespark/payments/medianet/BoundedRunner.kt

@@ -0,0 +1,116 @@
+package dev.firespark.payments.medianet
+
+import android.util.Log
+import expo.modules.kotlin.Promise
+import java.util.concurrent.ExecutorService
+import java.util.concurrent.Executors
+import java.util.concurrent.RejectedExecutionException
+import java.util.concurrent.ThreadFactory
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicInteger
+import org.json.JSONObject
+
+const val TIMEOUT_CODE = "MEDIANET_TIMEOUT"
+const val ERROR_CODE = "MEDIANET_ERROR"
+
+/**
+ * Runs each pinpad call off the JS thread, one at a time (the pinpad serves one frame per
+ * connection), with a ceiling. A socket stuck past its own timeout cannot be killed; on timeout
+ * the promise is rejected and the thread is replaced so later calls do not queue behind it.
+ */
+internal class BoundedRunner {
+  @Volatile private var serial: ExecutorService = Executors.newSingleThreadExecutor(daemon("medianet-native"))
+  private val watchdog = Executors.newSingleThreadScheduledExecutor(daemon("medianet-watchdog"))
+  private val consecutiveTimeouts = AtomicInteger(0)
+  private val executorReplacements = AtomicInteger(0)
+  @Volatile private var lastTimeoutOperation: String? = null
+  @Volatile private var lastCallOperation: String? = null
+  @Volatile private var lastCallDurationMs = 0L
+
+  fun run(operation: String, timeoutMs: Long, promise: Promise, block: () -> Any?) {
+    val settled = AtomicBoolean(false)
+    val startedAt = System.currentTimeMillis()
+    val target = serial
+    MedianetDebug.log("runner.$operation › queued timeoutMs=$timeoutMs")
+    val timer = watchdog.schedule({
+      if (settled.compareAndSet(false, true)) {
+        val count = consecutiveTimeouts.incrementAndGet()
+        lastTimeoutOperation = operation
+        val replaced = replaceSerial(target)
+        Log.w(TAG, "$operation timed out after ${timeoutMs}ms consecutive=$count executorReplaced=$replaced")
+        promise.reject(TIMEOUT_CODE, timeoutJson(operation, timeoutMs, count, replaced), null)
+      }
+    }, timeoutMs, TimeUnit.MILLISECONDS)
+    try {
+      target.execute {
+        val thread = Thread.currentThread().name
+        val waited = System.currentTimeMillis() - startedAt
+        MedianetDebug.log("runner.$operation › running thread=$thread waited=${waited}ms")
+        val outcome = runCatching(block)
+        timer.cancel(false)
+        if (!settled.compareAndSet(false, true)) {
+          Log.w(TAG, "$operation returned late after ${System.currentTimeMillis() - startedAt}ms; result discarded")
+          return@execute
+        }
+        lastCallOperation = operation
+        lastCallDurationMs = System.currentTimeMillis() - startedAt
+        val ok = outcome.isSuccess
+        val error = outcome.exceptionOrNull()?.message
+        MedianetDebug.log("runner.$operation › settled ok=$ok error=$error ms=$lastCallDurationMs")
+        outcome
+          .onSuccess {
+            consecutiveTimeouts.set(0)
+            promise.resolve(it)
+          }
+          .onFailure { promise.reject(ERROR_CODE, it.message ?: "$operation failed", it) }
+      }
+    } catch (error: RejectedExecutionException) {
+      timer.cancel(false)
+      if (settled.compareAndSet(false, true)) {
+        promise.reject(ERROR_CODE, "executor rejected $operation: ${error.message}", error)
+      }
+    }
+  }
+
+  fun health(): Map<String, Any?> = mapOf(
+    "consecutiveTimeouts" to consecutiveTimeouts.get(),
+    "executorReplacements" to executorReplacements.get(),
+    "lastTimeoutOperation" to lastTimeoutOperation,
+    "lastCallOperation" to lastCallOperation,
+    "lastCallDurationMs" to lastCallDurationMs
+  )
+
+  fun shutdown() {
+    serial.shutdown()
+    watchdog.shutdownNow()
+  }
+
+  @Synchronized
+  private fun replaceSerial(stuck: ExecutorService): Boolean {
+    if (serial !== stuck) return false
+    serial = Executors.newSingleThreadExecutor(daemon("medianet-native"))
+    executorReplacements.incrementAndGet()
+    stuck.shutdown()
+    return true
+  }
+
+  private fun timeoutJson(operation: String, timeoutMs: Long, count: Int, replaced: Boolean): String =
+    JSONObject()
+      .put("operation", operation)
+      .put("timeoutMs", timeoutMs)
+      .put("consecutiveTimeouts", count)
+      .put("executorReplaced", replaced)
+      .toString()
+
+  private companion object {
+    const val TAG = "Medianet"
+
+    fun daemon(name: String): ThreadFactory {
+      val sequence = AtomicInteger(0)
+      return ThreadFactory { runnable ->
+        Thread(runnable, "$name-${sequence.incrementAndGet()}").apply { isDaemon = true }
+      }
+    }
+  }
+}

package/android/src/main/java/dev/firespark/payments/medianet/MedianetBridge.kt

@@ -0,0 +1,102 @@
+package dev.firespark.payments.medianet
+
+import cajapinpad.CifradoTramas
+import cajapinpad.Conexion
+import cajapinpad.ProccessData
+
+private const val HASH_LENGTH = 32
+private const val NETWORK_MEDIANET = "2"
+
+/**
+ * The only class that touches `CajaPinPadLibrary_V3.jar`. Field order and fillers match the legacy
+ * Ecuador kiosk module (Medianet frames `LT`, `CP`, `PC`, `PP`); the library frames and hashes them.
+ */
+internal class MedianetBridge {
+  private val data: ProccessData = ProccessData.getInstance()
+
+  fun linkTest(params: ConnectionParams): FrameResponse =
+    send(params.host, params.port, params.timeoutMs, arrayOf("LT"))
+
+  fun setup(params: SetupParams): FrameResponse {
+    val host = " ".repeat(15)
+    val port = " ".repeat(6)
+    val fields = arrayOf(
+      "CP",
+      params.ip,
+      params.mask,
+      params.gateway,
+      host, port, // switch main host
+      host, port, // switch alternate host
+      host, port, // network 2 main host
+      host, port, // network 2 alternate host
+      params.listenPort
+    )
+    return send(params.host, params.port, params.timeoutMs, fields)
+  }
+
+  fun control(params: ControlParams): FrameResponse {
+    val fields = arrayOf(
+      "PC",
+      params.batch,
+      params.sequential,
+      " ".repeat(12),
+      params.mid,
+      params.tid,
+      " ".repeat(23),
+      params.cid,
+      NETWORK_MEDIANET
+    )
+    return send(params.host, params.port, params.timeoutMs, fields)
+  }
+
+  /** `PP` with transaction type `01` (sale), `03` (void) or `04` (reverse). */
+  fun authorize(type: String, params: AuthorizationParams): FrameResponse {
+    val blank = " ".repeat(12)
+    val fields = arrayOf(
+      "PP",
+      type,
+      NETWORK_MEDIANET,
+      "00", // deferred code
+      "  ", // deferred term
+      "  ", // grace months
+      " ",
+      params.total,
+      params.subtotal,
+      params.baseWithoutTax,
+      params.tax,
+      blank, // service tax
+      blank, // tip
+      blank, // fixed amount
+      params.sequential,
+      params.hour,
+      params.date,
+      params.authorization,
+      params.mid,
+      params.tid,
+      params.cid,
+      " ".repeat(20)
+    )
+    return send(params.host, params.port, params.timeoutMs, fields)
+  }
+
+  private fun send(host: String, port: Int, timeoutMs: Int, fields: Array<String>): FrameResponse {
+    val type = fields.firstOrNull() ?: "?"
+    MedianetDebug.log("bridge › $type $host:$port timeoutMs=$timeoutMs")
+    val cipher = CifradoTramas()
+    val frame = fields + data.padright(cipher.getHash(), HASH_LENGTH, ' ')
+    val connection = Conexion()
+    connection.sendData(host, port, data.getFinalData(frame), timeoutMs)
+    val received = connection.getDataRecived()
+    if (received == null || received.isEmpty()) {
+      throw IllegalStateException("Medianet pinpad did not answer ($host:$port)")
+    }
+    val response = data.hex2AsciiStr(data.byte2hex(received))
+    if (response.length < HASH_LENGTH) {
+      throw IllegalStateException("Medianet incomplete response (len=${response.length})")
+    }
+    val hash = response.substring(response.length - HASH_LENGTH)
+    val valid = cipher.validateHash(hash)
+    MedianetDebug.log("bridge › $type len=${response.length} hash=$valid")
+    return FrameResponse(response, valid)
+  }
+}

package/android/src/main/java/dev/firespark/payments/medianet/MedianetDebug.kt

@@ -0,0 +1,16 @@
+package dev.firespark.payments.medianet
+
+import android.util.Log
+
+/** Process-wide gate for `MEDIANET_DEBUG` logcat lines. Off until `setLogs`. */
+internal object MedianetDebug {
+  const val TAG = "MEDIANET_DEBUG"
+
+  @Volatile
+  var enabled: Boolean = false
+
+  fun log(message: String) {
+    if (!enabled) return
+    Log.d(TAG, message)
+  }
+}

package/android/src/main/java/dev/firespark/payments/medianet/MedianetModule.kt

@@ -0,0 +1,51 @@
+package dev.firespark.payments.medianet
+
+import expo.modules.kotlin.Promise
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+/** Grace over the socket timeout before the runner gives up on a stuck call. */
+private const val CEILING_GRACE_MS = 5_000L
+
+class MedianetModule : Module() {
+  private val runner = BoundedRunner()
+  private val bridge = MedianetBridge()
+
+  private fun ceiling(timeoutMs: Int) = timeoutMs.toLong() + CEILING_GRACE_MS
+
+  override fun definition() = ModuleDefinition {
+    Name("Medianet")
+
+    AsyncFunction("linkTest") { params: ConnectionParams, promise: Promise ->
+      runner.run("linkTest", ceiling(params.timeoutMs), promise) { bridge.linkTest(params).toMap() }
+    }
+
+    AsyncFunction("setup") { params: SetupParams, promise: Promise ->
+      runner.run("setup", ceiling(params.timeoutMs), promise) { bridge.setup(params).toMap() }
+    }
+
+    AsyncFunction("control") { params: ControlParams, promise: Promise ->
+      runner.run("control", ceiling(params.timeoutMs), promise) { bridge.control(params).toMap() }
+    }
+
+    AsyncFunction("sale") { params: AuthorizationParams, promise: Promise ->
+      runner.run("sale", ceiling(params.timeoutMs), promise) { bridge.authorize("01", params).toMap() }
+    }
+
+    AsyncFunction("void") { params: AuthorizationParams, promise: Promise ->
+      runner.run("void", ceiling(params.timeoutMs), promise) { bridge.authorize("03", params).toMap() }
+    }
+
+    AsyncFunction("reverse") { params: AuthorizationParams, promise: Promise ->
+      runner.run("reverse", ceiling(params.timeoutMs), promise) { bridge.authorize("04", params).toMap() }
+    }
+
+    Function("setLogs") { enabled: Boolean ->
+      MedianetDebug.enabled = enabled
+    }
+
+    Function("getHealth") { runner.health() }
+
+    OnDestroy { runner.shutdown() }
+  }
+}

package/android/src/main/java/dev/firespark/payments/medianet/MedianetRecords.kt

@@ -0,0 +1,53 @@
+package dev.firespark.payments.medianet
+
+import expo.modules.kotlin.records.Field
+import expo.modules.kotlin.records.Record
+
+/** Every frame field arrives already padded by the JS client (`frames.ts`). */
+class ConnectionParams : Record {
+  @Field val host: String = ""
+  @Field val port: Int = 0
+  @Field val timeoutMs: Int = 0
+}
+
+class SetupParams : Record {
+  @Field val host: String = ""
+  @Field val port: Int = 0
+  @Field val timeoutMs: Int = 0
+  @Field val ip: String = ""
+  @Field val mask: String = ""
+  @Field val gateway: String = ""
+  @Field val listenPort: String = ""
+}
+
+class ControlParams : Record {
+  @Field val host: String = ""
+  @Field val port: Int = 0
+  @Field val timeoutMs: Int = 0
+  @Field val batch: String = ""
+  @Field val sequential: String = ""
+  @Field val mid: String = ""
+  @Field val tid: String = ""
+  @Field val cid: String = ""
+}
+
+class AuthorizationParams : Record {
+  @Field val host: String = ""
+  @Field val port: Int = 0
+  @Field val timeoutMs: Int = 0
+  @Field val total: String = ""
+  @Field val subtotal: String = ""
+  @Field val baseWithoutTax: String = ""
+  @Field val tax: String = ""
+  @Field val sequential: String = ""
+  @Field val hour: String = ""
+  @Field val date: String = ""
+  @Field val authorization: String = ""
+  @Field val mid: String = ""
+  @Field val tid: String = ""
+  @Field val cid: String = ""
+}
+
+data class FrameResponse(val response: String, val hashValid: Boolean) {
+  fun toMap(): Map<String, Any> = mapOf("response" to response, "hashValid" to hashValid)
+}

package/app.plugin.js

@@ -0,0 +1 @@
+module.exports = require("./plugin/withMedianet.cjs");

package/dist/index.d.mts

@@ -0,0 +1,225 @@
+//#region src/types.d.ts
+/** Where the pinpad listens on the LAN; `timeoutMs` is the socket timeout. */
+type MedianetConnection = {
+  host: string;
+  port: number;
+  timeoutMs: number;
+};
+/** `CP`: network settings of the pinpad. Fields already padded. */
+type MedianetSetupParams = MedianetConnection & {
+  ip: string;
+  mask: string;
+  gateway: string;
+  listenPort: string;
+};
+/** `PC`: commercial control (batch, sequential, MID, TID, CID). Padded. */
+type MedianetControlParams = MedianetConnection & {
+  batch: string;
+  sequential: string;
+  mid: string;
+  tid: string;
+  cid: string;
+};
+/** `PP` sale, void or reverse. Amounts are 12-digit cents, all padded. */
+type MedianetAuthorizationParams = MedianetConnection & {
+  total: string;
+  subtotal: string;
+  baseWithoutTax: string;
+  tax: string;
+  /** Sequential of the original sale; blanks on a sale. */
+  sequential: string;
+  /** `HHmmss`. */
+  hour: string;
+  /** `YYYYMMDD`. */
+  date: string;
+  /** Authorization number of the original sale; blanks on a sale. */
+  authorization: string;
+  mid: string;
+  tid: string;
+  cid: string;
+};
+/** Raw ASCII answer of the pinpad and whether its hash checked out. */
+type MedianetFrameResponse = {
+  response: string;
+  hashValid: boolean;
+};
+type MedianetHealth = {
+  consecutiveTimeouts: number;
+  executorReplacements: number;
+  lastTimeoutOperation: string | null;
+  lastCallOperation: string | null;
+  lastCallDurationMs: number;
+};
+/** Shape of the Expo module registered as `Medianet` on Android. */
+type MedianetNativeModule = {
+  linkTest: (params: MedianetConnection) => Promise<MedianetFrameResponse>;
+  setup: (params: MedianetSetupParams) => Promise<MedianetFrameResponse>;
+  control: (params: MedianetControlParams) => Promise<MedianetFrameResponse>;
+  sale: (params: MedianetAuthorizationParams) => Promise<MedianetFrameResponse>;
+  void: (params: MedianetAuthorizationParams) => Promise<MedianetFrameResponse>;
+  reverse: (params: MedianetAuthorizationParams) => Promise<MedianetFrameResponse>;
+  getHealth: () => MedianetHealth;
+  /** Gates `MEDIANET_DEBUG` logcat lines. Off until the adapter enables it. */
+  setLogs: (enabled: boolean) => void;
+};
+//#endregion
+//#region src/client.d.ts
+type MedianetClientOptions = {
+  /** Extra wait after the native ceiling before the JS side gives up. */
+  graceMs?: number;
+};
+type Frame = Promise<MedianetFrameResponse>;
+type MedianetClient = {
+  readonly available: boolean;
+  /** `LT`: link test. */
+  linkTest: (params: MedianetConnection) => Frame;
+  /** `CP`: network settings of the pinpad. */
+  setup: (params: MedianetSetupParams) => Frame;
+  /** `PC`: opens the batch of the day with MID, TID and CID. */
+  control: (params: MedianetControlParams) => Frame;
+  /** `PP` / `01`. */
+  sale: (params: MedianetAuthorizationParams) => Frame;
+  /** `PP` / `03`: void of an approved sale. */
+  void: (params: MedianetAuthorizationParams) => Frame;
+  /** `PP` / `04`: reverse of a sale with an unknown result. */
+  reverse: (params: MedianetAuthorizationParams) => Frame;
+  getHealth: () => MedianetHealth | null;
+};
+declare const createMedianetClient: (native: MedianetNativeModule | null, options?: MedianetClientOptions) => MedianetClient;
+//#endregion
+//#region src/constants.d.ts
+/** Pinpad result codes of every frame (legacy kiosk; ficha §11). */
+declare const MEDIANET_PINPAD_CODE: {
+  readonly OK: "00";
+  readonly FRAME_ERROR: "01";
+  readonly CONNECTION_ERROR: "02";
+  readonly PROCESS_ERROR: "20";
+  readonly TIMEOUT: "TO";
+  readonly PINPAD_ERROR: "ER";
+};
+/** Authorizer response code of an approved `PP`. */
+declare const MEDIANET_APPROVED = "00";
+declare const MEDIANET_TIMEOUT_CODE = "MEDIANET_TIMEOUT";
+/**
+ * Socket timeout floor: the pinpad waits for card and PIN inside one
+ * frame, so shorter values abort real payments (legacy kiosk).
+ */
+declare const MEDIANET_MIN_TIMEOUT_MS = 60000;
+/** Native ceiling = socket timeout + 5 s (`MedianetModule.kt`). */
+declare const MEDIANET_NATIVE_GRACE_MS = 5000;
+/** Extra wait of the JS backstop after the native ceiling. */
+declare const MEDIANET_JS_GRACE_MS = 5000;
+declare const MEDIANET_DEFAULT_TIME_ZONE = "America/Guayaquil";
+type MedianetOperation = "linkTest" | "setup" | "control" | "sale" | "void" | "reverse";
+//#endregion
+//#region src/debug.d.ts
+/** Turns console and Android logcat traces on or off. Default is off. */
+declare const setMedianetLogs: (value: boolean) => void;
+/** Logs one step: `[MEDIANET_DEBUG] scope › event { data }`. */
+declare const medianetDebug: (scope: string, event: string, data?: unknown) => void;
+/** Logs the input, the output or the error, and the duration of a call. */
+declare const medianetDebugCall: <T>(scope: string, input: unknown, call: () => Promise<T>) => Promise<T>;
+//#endregion
+//#region src/errors.d.ts
+declare class MedianetUnavailableError extends Error {
+  readonly code = "MEDIANET_UNAVAILABLE";
+  constructor();
+}
+type MedianetTimeoutInfo = {
+  operation: string;
+  timeoutMs: number;
+  /** `native`: the Kotlin ceiling fired; `js`: the native call never settled. */
+  source: "native" | "js";
+};
+declare class MedianetTimeoutError extends Error {
+  readonly code = "MEDIANET_TIMEOUT";
+  readonly info: MedianetTimeoutInfo;
+  constructor(info: MedianetTimeoutInfo);
+}
+/** Turns the native `MEDIANET_TIMEOUT` rejection (JSON message) into a typed error. */
+declare const toMedianetTimeout: (error: unknown) => MedianetTimeoutError | null;
+//#endregion
+//#region src/frames.d.ts
+/** Merchant id: 15, space-padded right. */
+declare const medianetMid: (mid: string) => string;
+/** Terminal id: 8, zero-padded left. */
+declare const medianetTid: (tid: string) => string;
+/** Cashier id: 15, space-padded right. */
+declare const medianetCid: (cid: string) => string;
+/** Amount in cents: 12, zero-padded left. */
+declare const medianetAmount: (cents: number) => string;
+/** `10.0.0.5` → `010.000.000.005`. */
+declare const medianetIp: (ip: string) => string;
+/** Network mask: 15, space-padded right (legacy kiosk). */
+declare const medianetMask: (mask: string) => string;
+/** Listen port of the pinpad: 6, zero-padded left. */
+declare const medianetListenPort: (port: number) => string;
+/** Original sequential / authorization of a void: 6, as returned. */
+declare const medianetReference: (value: string | null | undefined) => string;
+/** Socket timeout in ms, never under the 60 s floor. */
+declare const medianetTimeoutMs: (timeoutMs?: number | null) => number;
+type MedianetDateTime = {
+  /** `YYYYMMDD`. */
+  date: string;
+  /** `HHmmss`. */
+  hour: string;
+  /** `DDMMYY`: batch of the day sent in `PC`. */
+  batch: string;
+};
+/** Store-local date and time; Ecuador by default. */
+declare const medianetDateTime: (date?: Date, timeZone?: string) => MedianetDateTime;
+/** `PC` sequential: last 2 chars of the cashier id + `0001` (legacy kiosk). */
+declare const medianetControlSequential: (cid: string) => string;
+//#endregion
+//#region src/parse.d.ts
+/** Answer of `CP` / `PC`: message type, pinpad code and text. */
+type MedianetStatusResponse = {
+  type: string;
+  code: string;
+  message: string;
+};
+/** Answer of `PP` (sale, void, reverse). Fields trimmed; blanks → `""`. */
+type MedianetAuthorizationResponse = MedianetStatusResponse & {
+  /** `02` Medianet (`01` Datafast, `03` Austro). */
+  network: string;
+  /** Authorizer response code; `00` approved. */
+  responseCode: string;
+  sequential: string;
+  batch: string;
+  /** `HHmmss`. */
+  hour: string;
+  /** `YYYYMMDD`. */
+  date: string;
+  authorization: string;
+  terminalId: string;
+  merchantId: string;
+  interest: string;
+  award: string;
+  acquirerCode: string;
+  acquirerName: string;
+  cardGroup: string;
+  /** Reading mode as returned by the pinpad. */
+  entryMode: string;
+  cardholder: string;
+  fixedAmount: string;
+  applicationLabel: string;
+  aid: string;
+  cryptogram: string;
+  pinVerification: string;
+  arqc: string;
+  tvr: string;
+  tsi: string;
+  /** Masked PAN, e.g. `41668200XXXX6319`. */
+  maskedPan: string;
+};
+/** Offsets from the legacy kiosk (`medianet.utils.ts`; ficha §8). */
+declare const parseMedianetAuthorization: (response: string) => MedianetAuthorizationResponse;
+/** `PC`: 2 filler chars between the code and the message. */
+declare const parseMedianetControl: (response: string) => MedianetStatusResponse;
+declare const parseMedianetSetup: (response: string) => MedianetStatusResponse;
+//#endregion
+//#region src/index.d.ts
+/** Shared client bound to the device's native module; one per app. */
+declare const medianet: MedianetClient;
+//#endregion
+export { MEDIANET_APPROVED, MEDIANET_DEFAULT_TIME_ZONE, MEDIANET_JS_GRACE_MS, MEDIANET_MIN_TIMEOUT_MS, MEDIANET_NATIVE_GRACE_MS, MEDIANET_PINPAD_CODE, MEDIANET_TIMEOUT_CODE, MedianetAuthorizationParams, MedianetAuthorizationResponse, MedianetClient, MedianetClientOptions, MedianetConnection, MedianetControlParams, MedianetDateTime, MedianetFrameResponse, MedianetHealth, MedianetNativeModule, MedianetOperation, MedianetSetupParams, MedianetStatusResponse, MedianetTimeoutError, MedianetTimeoutInfo, MedianetUnavailableError, createMedianetClient, medianet, medianetAmount, medianetCid, medianetControlSequential, medianetDateTime, medianetDebug, medianetDebugCall, medianetIp, medianetListenPort, medianetMask, medianetMid, medianetReference, medianetTid, medianetTimeoutMs, parseMedianetAuthorization, parseMedianetControl, parseMedianetSetup, setMedianetLogs, toMedianetTimeout };

package/dist/index.mjs

@@ -0,0 +1,325 @@
+import { requireOptionalNativeModule } from "expo";
+//#region src/constants.ts
+/** Pinpad result codes of every frame (legacy kiosk; ficha §11). */
+const MEDIANET_PINPAD_CODE = {
+	OK: "00",
+	FRAME_ERROR: "01",
+	CONNECTION_ERROR: "02",
+	PROCESS_ERROR: "20",
+	TIMEOUT: "TO",
+	PINPAD_ERROR: "ER"
+};
+/** Authorizer response code of an approved `PP`. */
+const MEDIANET_APPROVED = "00";
+const MEDIANET_TIMEOUT_CODE = "MEDIANET_TIMEOUT";
+/**
+* Socket timeout floor: the pinpad waits for card and PIN inside one
+* frame, so shorter values abort real payments (legacy kiosk).
+*/
+const MEDIANET_MIN_TIMEOUT_MS = 6e4;
+/** Native ceiling = socket timeout + 5 s (`MedianetModule.kt`). */
+const MEDIANET_NATIVE_GRACE_MS = 5e3;
+/** Extra wait of the JS backstop after the native ceiling. */
+const MEDIANET_JS_GRACE_MS = 5e3;
+const MEDIANET_DEFAULT_TIME_ZONE = "America/Guayaquil";
+//#endregion
+//#region src/native.ts
+/** `null` on iOS, web, or an Android build without the Medianet plugin. */
+const medianetNative = requireOptionalNativeModule("Medianet");
+//#endregion
+//#region src/debug.ts
+const TAG = "[MEDIANET_DEBUG]";
+let enabled = false;
+const elapsed = (startedAt) => Date.now() - startedAt;
+/** The pinpad frame carries the cardholder, the cryptogram and a PAN. */
+const frameOf = (value) => {
+	if (!("response" in value) || !("hashValid" in value)) return null;
+	const frame = value;
+	if (typeof frame.response !== "string") return null;
+	if (typeof frame.hashValid !== "boolean") return null;
+	return {
+		len: frame.response.length,
+		hashValid: frame.hashValid
+	};
+};
+const safe = (value) => {
+	if (value instanceof Map) return Object.fromEntries(value);
+	if (value instanceof Error) {
+		const code = value.code;
+		return {
+			name: value.name,
+			message: value.message,
+			code
+		};
+	}
+	if (value && typeof value === "object") {
+		const frame = frameOf(value);
+		if (frame) return frame;
+	}
+	return value;
+};
+/** Turns console and Android logcat traces on or off. Default is off. */
+const setMedianetLogs = (value) => {
+	enabled = value;
+	medianetNative?.setLogs(value);
+};
+/** Logs one step: `[MEDIANET_DEBUG] scope › event { data }`. */
+const medianetDebug = (scope, event, data) => {
+	if (!enabled) return;
+	const time = (/* @__PURE__ */ new Date()).toISOString();
+	if (data === void 0) return console.log(TAG, time, `${scope} › ${event}`);
+	console.log(TAG, time, `${scope} › ${event}`, safe(data));
+};
+/** Logs the input, the output or the error, and the duration of a call. */
+const medianetDebugCall = async (scope, input, call) => {
+	const startedAt = Date.now();
+	medianetDebug(scope, "→ in", input);
+	try {
+		const output = await call();
+		const ms = elapsed(startedAt);
+		medianetDebug(scope, "← out", {
+			output: safe(output),
+			ms
+		});
+		return output;
+	} catch (error) {
+		const ms = elapsed(startedAt);
+		medianetDebug(scope, "✕ error", {
+			error: safe(error),
+			ms
+		});
+		throw error;
+	}
+};
+//#endregion
+//#region src/errors.ts
+var MedianetUnavailableError = class extends Error {
+	code = "MEDIANET_UNAVAILABLE";
+	constructor() {
+		super("Medianet native module is not available (Android build with the Medianet plugin required)");
+		this.name = "MedianetUnavailableError";
+	}
+};
+var MedianetTimeoutError = class extends Error {
+	code = MEDIANET_TIMEOUT_CODE;
+	info;
+	constructor(info) {
+		super(`Medianet ${info.operation} timed out after ${info.timeoutMs} ms`);
+		this.name = "MedianetTimeoutError";
+		this.info = info;
+	}
+};
+const asRecord = (value) => {
+	if (typeof value !== "object" || value === null) return null;
+	return value;
+};
+const parseJson = (value) => {
+	try {
+		return asRecord(JSON.parse(String(value))) ?? {};
+	} catch {
+		return {};
+	}
+};
+/** Turns the native `MEDIANET_TIMEOUT` rejection (JSON message) into a typed error. */
+const toMedianetTimeout = (error) => {
+	const record = asRecord(error);
+	if (!record || record.code !== "MEDIANET_TIMEOUT") return null;
+	const payload = parseJson(record.message);
+	return new MedianetTimeoutError({
+		operation: typeof payload.operation === "string" ? payload.operation : "unknown",
+		timeoutMs: typeof payload.timeoutMs === "number" ? payload.timeoutMs : 0,
+		source: "native"
+	});
+};
+//#endregion
+//#region src/client.ts
+const createMedianetClient = (native, options = {}) => {
+	const graceMs = options.graceMs ?? 5e3;
+	const boundedCall = async (operation, params, call) => {
+		if (!native) throw new MedianetUnavailableError();
+		const timeoutMs = params.timeoutMs + MEDIANET_NATIVE_GRACE_MS + graceMs;
+		let timer;
+		const backstop = new Promise((_, reject) => {
+			const info = {
+				operation,
+				timeoutMs,
+				source: "js"
+			};
+			const fire = () => reject(new MedianetTimeoutError(info));
+			timer = setTimeout(fire, timeoutMs);
+		});
+		try {
+			return await Promise.race([call(native, params), backstop]);
+		} catch (error) {
+			let timeout = null;
+			if (error instanceof MedianetTimeoutError) timeout = error;
+			else timeout = toMedianetTimeout(error);
+			if (!timeout) throw error;
+			medianetDebug(`client.${operation}`, "timeout", timeout.info);
+			throw timeout;
+		} finally {
+			clearTimeout(timer);
+		}
+	};
+	const bounded = async (operation, params, call) => {
+		const run = () => boundedCall(operation, params, call);
+		return medianetDebugCall(`client.${operation}`, params, run);
+	};
+	return {
+		available: native !== null,
+		linkTest: (params) => bounded("linkTest", params, (m, p) => m.linkTest(p)),
+		setup: (params) => bounded("setup", params, (m, p) => m.setup(p)),
+		control: (params) => bounded("control", params, (m, p) => m.control(p)),
+		sale: (params) => bounded("sale", params, (m, p) => m.sale(p)),
+		void: (params) => bounded("void", params, (m, p) => m.void(p)),
+		reverse: (params) => bounded("reverse", params, (m, p) => m.reverse(p)),
+		getHealth: () => {
+			const health = native?.getHealth() ?? null;
+			medianetDebug("client.getHealth", "← out", health);
+			return health;
+		}
+	};
+};
+//#endregion
+//#region src/frames.ts
+const fit = (value, length, field) => {
+	if (value.length > length) throw new RangeError(`Medianet ${field} longer than ${length}: ${value}`);
+	return value;
+};
+const padEnd = (value, length, field) => {
+	return fit(value.trim(), length, field).padEnd(length, " ");
+};
+const padStart = (value, length, field, fill = "0") => {
+	return fit(value.trim(), length, field).padStart(length, fill);
+};
+/** Merchant id: 15, space-padded right. */
+const medianetMid = (mid) => padEnd(mid, 15, "MID");
+/** Terminal id: 8, zero-padded left. */
+const medianetTid = (tid) => padStart(tid, 8, "TID");
+/** Cashier id: 15, space-padded right. */
+const medianetCid = (cid) => padEnd(cid, 15, "CID");
+/** Amount in cents: 12, zero-padded left. */
+const medianetAmount = (cents) => {
+	if (!Number.isInteger(cents) || cents < 0) throw new RangeError(`Invalid Medianet amount: ${cents}`);
+	return padStart(String(cents), 12, "amount");
+};
+/** `10.0.0.5` → `010.000.000.005`. */
+const medianetIp = (ip) => {
+	const padded = ip.trim().split(".").map((octet) => octet.padStart(3, "0")).join(".");
+	return fit(padded, 15, "IP");
+};
+/** Network mask: 15, space-padded right (legacy kiosk). */
+const medianetMask = (mask) => padEnd(mask, 15, "mask");
+/** Listen port of the pinpad: 6, zero-padded left. */
+const medianetListenPort = (port) => {
+	return padStart(String(port), 6, "port");
+};
+/** Original sequential / authorization of a void: 6, as returned. */
+const medianetReference = (value) => {
+	return padStart(value ?? "", 6, "reference", " ");
+};
+/** Socket timeout in ms, never under the 60 s floor. */
+const medianetTimeoutMs = (timeoutMs) => {
+	const value = Number(timeoutMs);
+	if (!Number.isFinite(value) || value <= 0) return MEDIANET_MIN_TIMEOUT_MS;
+	return Math.max(Math.round(value), MEDIANET_MIN_TIMEOUT_MS);
+};
+const formatters = /* @__PURE__ */ new Map();
+const formatterFor = (timeZone) => {
+	const cached = formatters.get(timeZone);
+	if (cached) return cached;
+	const options = {
+		timeZone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit",
+		hourCycle: "h23"
+	};
+	const formatter = new Intl.DateTimeFormat("en-US", options);
+	formatters.set(timeZone, formatter);
+	return formatter;
+};
+/** Store-local date and time; Ecuador by default. */
+const medianetDateTime = (date = /* @__PURE__ */ new Date(), timeZone = MEDIANET_DEFAULT_TIME_ZONE) => {
+	const parts = Object.fromEntries(formatterFor(timeZone).formatToParts(date).map((part) => [part.type, part.value]));
+	const { year = "", month = "", day = "" } = parts;
+	return {
+		date: `${year}${month}${day}`,
+		hour: `${parts.hour}${parts.minute}${parts.second}`,
+		batch: `${day}${month}${year.slice(-2)}`
+	};
+};
+/** `PC` sequential: last 2 chars of the cashier id + `0001` (legacy kiosk). */
+const medianetControlSequential = (cid) => {
+	return `${cid.trim().slice(-2).padStart(2, "0")}0001`;
+};
+//#endregion
+//#region src/parse.ts
+/** Drops the 4-digit length prefix the library puts before the frame. */
+const payloadOf = (response) => response.slice(4);
+const slice = (data, from, to) => {
+	return data.slice(from, to).trim();
+};
+/** Offsets from the legacy kiosk (`medianet.utils.ts`; ficha §8). */
+const parseMedianetAuthorization = (response) => {
+	const data = payloadOf(response);
+	const at = (from, to) => slice(data, from, to);
+	return {
+		type: at(0, 2),
+		code: at(2, 4),
+		network: at(4, 6),
+		responseCode: at(6, 8),
+		message: at(8, 28),
+		sequential: at(28, 34),
+		batch: at(34, 40),
+		hour: at(40, 46),
+		date: at(46, 54),
+		authorization: at(54, 60),
+		terminalId: at(60, 68),
+		merchantId: at(68, 83),
+		interest: at(83, 95),
+		award: at(95, 175),
+		acquirerCode: at(175, 178),
+		acquirerName: at(178, 208),
+		cardGroup: at(208, 233),
+		entryMode: at(233, 235),
+		cardholder: at(235, 275),
+		fixedAmount: at(275, 287),
+		applicationLabel: at(287, 307),
+		aid: at(307, 327),
+		cryptogram: at(327, 349),
+		pinVerification: at(349, 364),
+		arqc: at(364, 380),
+		tvr: at(380, 390),
+		tsi: at(390, 394),
+		maskedPan: at(394, 419)
+	};
+};
+/** `PC`: 2 filler chars between the code and the message. */
+const parseMedianetControl = (response) => {
+	const data = payloadOf(response);
+	const at = (from, to) => slice(data, from, to);
+	return {
+		type: at(0, 2),
+		code: at(2, 4),
+		message: at(6, 26)
+	};
+};
+const parseMedianetSetup = (response) => {
+	const data = payloadOf(response);
+	const at = (from, to) => slice(data, from, to);
+	return {
+		type: at(0, 2),
+		code: at(2, 4),
+		message: at(4, 24)
+	};
+};
+//#endregion
+//#region src/index.ts
+/** Shared client bound to the device's native module; one per app. */
+const medianet = createMedianetClient(medianetNative);
+//#endregion
+export { MEDIANET_APPROVED, MEDIANET_DEFAULT_TIME_ZONE, MEDIANET_JS_GRACE_MS, MEDIANET_MIN_TIMEOUT_MS, MEDIANET_NATIVE_GRACE_MS, MEDIANET_PINPAD_CODE, MEDIANET_TIMEOUT_CODE, MedianetTimeoutError, MedianetUnavailableError, createMedianetClient, medianet, medianetAmount, medianetCid, medianetControlSequential, medianetDateTime, medianetDebug, medianetDebugCall, medianetIp, medianetListenPort, medianetMask, medianetMid, medianetReference, medianetTid, medianetTimeoutMs, parseMedianetAuthorization, parseMedianetControl, parseMedianetSetup, setMedianetLogs, toMedianetTimeout };

package/expo-module.config.json

@@ -0,0 +1,6 @@
+{
+  "platforms": ["android"],
+  "android": {
+    "modules": ["dev.firespark.payments.medianet.MedianetModule"]
+  }
+}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@fire-spark/payments-medianet-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.13.0",
+  "description": "Fire Spark native client for the Medianet pinpad (Ecuador) on Android: CajaPinPad V3 TCP bridge shared by the Medianet adapters",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "android/build.gradle",
+    "android/src",
+    "plugin",
+    "app.plugin.js",
+    "expo-module.config.json"
+  ],
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./app.plugin": "./app.plugin.js",
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "expo": ">=57"
+  },
+  "devDependencies": {
+    "expo": "~57.0.25",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "tsdown": {
+    "entry": [
+      "src/index.ts"
+    ],
+    "format": [
+      "esm"
+    ],
+    "platform": "neutral",
+    "dts": {
+      "tsconfig": "tsconfig.build.json"
+    },
+    "clean": true,
+    "deps": {
+      "neverBundle": [
+        "expo"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "check-types": "tsc --noEmit",
+    "test:utils": "vitest run",
+    "lint": "oxlint ./src --max-warnings=0",
+    "format": "oxfmt ./src",
+    "check-format": "oxfmt --check ./src"
+  }
 }

package/plugin/withMedianet.cjs

@@ -0,0 +1,57 @@
+const {
+  AndroidConfig,
+  withAppBuildGradle,
+  withDangerousMod
+} = require("expo/config-plugins");
+const fs = require("fs");
+const path = require("path");
+
+const JAR = "CajaPinPadLibrary_V3.jar";
+const MARKER = "// @fire-spark/payments-medianet-client";
+
+/**
+ * Expected layout of `binariesDir` (per environment, never committed):
+ *   CajaPinPadLibrary_V3.jar   (Medianet / WPOSS `cajapinpad` library)
+ */
+const withMedianetBinaries = (config, { binariesDir }) =>
+  withDangerousMod(config, [
+    "android",
+    async cfg => {
+      const source = path.resolve(cfg.modRequest.projectRoot, binariesDir);
+      const jar = path.join(source, JAR);
+      if (!fs.existsSync(jar)) {
+        throw new Error(`[medianet] missing ${jar}; set binariesDir to the Medianet files of this environment`);
+      }
+      const target = path.join(cfg.modRequest.platformProjectRoot, "app", "libs", JAR);
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.copyFileSync(jar, target);
+      return cfg;
+    }
+  ]);
+
+const gradleBlock = `
+${MARKER}
+dependencies {
+  implementation files("libs/${JAR}")
+}
+`;
+
+const withMedianetGradle = config =>
+  withAppBuildGradle(config, cfg => {
+    if (!cfg.modResults.contents.includes(MARKER)) {
+      cfg.modResults.contents += gradleBlock;
+    }
+    return cfg;
+  });
+
+/** @param {{ binariesDir: string }} options */
+const withMedianet = (config, options = {}) => {
+  if (!options.binariesDir) {
+    throw new Error("[medianet] the plugin needs { binariesDir }");
+  }
+  config = AndroidConfig.Permissions.withPermissions(config, ["android.permission.INTERNET"]);
+  config = withMedianetBinaries(config, options);
+  return withMedianetGradle(config);
+};
+
+module.exports = withMedianet;

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.