@fire-spark/payments-clisitef-client 0.0.0-stage → 0.7.1

package/android/build.gradle

@@ -0,0 +1,20 @@
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'dev.firespark.payments.clisitef'
+version = '0.1.0'
+
+android {
+  namespace "dev.firespark.payments.clisitef"
+  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/clisitef-android.jar")
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,4 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.INTERNET" />
+  <uses-feature android:name="android.hardware.usb.host" android:required="false" />
+</manifest>

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

@@ -0,0 +1,141 @@
+package dev.firespark.payments.clisitef
+
+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 = "CLISITEF_TIMEOUT"
+const val ERROR_CODE = "CLISITEF_ERROR"
+
+internal enum class Lane {
+  /** The library is stateful and not thread-safe: one ordered thread, replaced when it hangs. */
+  SERIAL,
+  /** `abortTransaction` is `synchronized` in the JAR: if the hung call holds the monitor, the next abort needs another thread. */
+  ABORT,
+  /** `closePinPad` / `disconnectSitef` are not `synchronized` and make a hung call's I/O fail. */
+  RECOVERY
+}
+
+/**
+ * Runs each CliSiTef call off the JS thread with a ceiling. A hung JNI call cannot be killed; on
+ * timeout the promise is rejected and the serial thread is replaced so later calls do not queue
+ * behind it (legacy incident 2026-09-12/13: kiosks dead for hours behind a stuck thread).
+ */
+internal class BoundedRunner {
+  @Volatile private var serial: ExecutorService = Executors.newSingleThreadExecutor(daemon("clisitef-native"))
+  private val abort: ExecutorService = Executors.newCachedThreadPool(daemon("clisitef-abort"))
+  private val recovery: ExecutorService = Executors.newCachedThreadPool(daemon("clisitef-recovery"))
+  private val watchdog = Executors.newSingleThreadScheduledExecutor(daemon("clisitef-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, lane: Lane = Lane.SERIAL, block: () -> Any?) {
+    val settled = AtomicBoolean(false)
+    val startedAt = System.currentTimeMillis()
+    val target = when (lane) {
+      Lane.SERIAL -> serial
+      Lane.ABORT -> abort
+      Lane.RECOVERY -> recovery
+    }
+    // TODO(debug-clisitef): remove.
+    Log.d(DEBUG_TAG, "runner.$operation › queued lane=$lane timeoutMs=$timeoutMs")
+    val timer = if (timeoutMs > 0) {
+      watchdog.schedule({
+        if (settled.compareAndSet(false, true)) {
+          val count = consecutiveTimeouts.incrementAndGet()
+          lastTimeoutOperation = operation
+          val replaced = lane == Lane.SERIAL && 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)
+    } else {
+      null
+    }
+    try {
+      target.execute {
+        // TODO(debug-clisitef): remove.
+        Log.d(DEBUG_TAG, "runner.$operation › running thread=${Thread.currentThread().name} waited=${System.currentTimeMillis() - startedAt}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
+        // TODO(debug-clisitef): remove.
+        Log.d(DEBUG_TAG, "runner.$operation › settled ok=${outcome.isSuccess} value=${outcome.getOrNull()} error=${outcome.exceptionOrNull()?.message} 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(appDirectory: String?): Map<String, Any?> = mapOf(
+    "consecutiveTimeouts" to consecutiveTimeouts.get(),
+    "executorReplacements" to executorReplacements.get(),
+    "lastTimeoutOperation" to lastTimeoutOperation,
+    "lastCallOperation" to lastCallOperation,
+    "lastCallDurationMs" to lastCallDurationMs,
+    "appDirectory" to appDirectory
+  )
+
+  fun shutdown() {
+    serial.shutdown()
+    abort.shutdown()
+    recovery.shutdown()
+    watchdog.shutdownNow()
+  }
+
+  /** The old thread is not interrupted: an interrupt does not free a blocking JNI call. */
+  @Synchronized
+  private fun replaceSerial(stuck: ExecutorService): Boolean {
+    if (serial !== stuck) return false
+    serial = Executors.newSingleThreadExecutor(daemon("clisitef-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)
+      .put("executorReplacements", executorReplacements.get())
+      .toString()
+
+  private companion object {
+    const val TAG = "CliSiTef"
+    // TODO(debug-clisitef): remove.
+    const val DEBUG_TAG = "CLISITEF_DEBUG"
+
+    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/clisitef/CliSiTefBridge.kt

@@ -0,0 +1,164 @@
+package dev.firespark.payments.clisitef
+
+import android.content.Context
+import android.util.Log
+import br.com.softwareexpress.sitef.android.CliSiTef
+import br.com.softwareexpress.sitef.android.ICliSiTefListener
+import java.io.File
+
+/** The only class that touches `clisitef-android.jar`; signatures match the legacy kiosk bridge. */
+internal class CliSiTefBridge(
+  private val context: Context,
+  private val onData: (DataEvent) -> Unit,
+  private val onResult: (stage: Int, resultCode: Int) -> Unit
+) {
+  private val clisitef: CliSiTef
+
+  private val listener = object : ICliSiTefListener {
+    override fun onData(stage: Int, command: Int, fieldId: Int, minLength: Int, maxLength: Int, input: ByteArray?) {
+      val text = input?.let { String(it) } ?: ""
+      // TODO(debug-clisitef): remove.
+      debug("listener.onData", "stage=$stage command=$command fieldId=$fieldId min=$minLength max=$maxLength input=\"$text\"")
+      onData(DataEvent(stage, command, fieldId, minLength, maxLength, text))
+    }
+
+    override fun onTransactionResult(stage: Int, resultCode: Int) {
+      // TODO(debug-clisitef): remove.
+      debug("listener.onTransactionResult", "stage=$stage resultCode=$resultCode")
+      onResult(stage, resultCode)
+    }
+  }
+
+  // TODO(debug-clisitef): remove with every `traced` / `debug` call.
+  private fun debug(scope: String, message: String) {
+    Log.d(DEBUG_TAG, "$scope › $message [thread=${Thread.currentThread().name}]")
+  }
+
+  // TODO(debug-clisitef): remove; call `block()` directly.
+  private fun <T> traced(scope: String, input: String, block: () -> T): T {
+    val startedAt = System.currentTimeMillis()
+    debug(scope, "→ jar in $input")
+    try {
+      val output = block()
+      debug(scope, "← jar out $output (${System.currentTimeMillis() - startedAt}ms)")
+      return output
+    } catch (error: Throwable) {
+      debug(scope, "✕ jar error ${error.javaClass.simpleName}: ${error.message} (${System.currentTimeMillis() - startedAt}ms)")
+      throw error
+    }
+  }
+
+  init {
+    // CliSiTef copies CLSIT on instantiation but does not overwrite an existing copy, and files/
+    // survives app updates; sync first so this APK's CLSIT wins.
+    syncClsit(context)
+    clisitef = CliSiTef(context)
+  }
+
+  val appDirectory: String
+    get() = context.applicationInfo.dataDir ?: context.filesDir.parent ?: ""
+
+  fun configure(params: ConfigureParams): Int {
+    val additional = withAppDir(params.additionalParams, appDirectory)
+    val input = "serverIp=${params.serverIp} storeCode=${params.storeCode} terminal=${params.terminalNumber} additional=$additional"
+    return traced("configure", input) {
+      clisitef.configure(params.serverIp, params.storeCode, params.terminalNumber, additional)
+    }
+  }
+
+  fun start(params: StartParams): Int {
+    val input = "modality=${params.modality} value=${params.value} coupon=${params.fiscalCoupon} " +
+      "date=${params.fiscalDate} time=${params.time} operator=${params.operator} restrictions=${params.restrictions}"
+    return traced("startTransaction", input) {
+      clisitef.startTransaction(
+        listener,
+        params.modality,
+        params.value,
+        params.fiscalCoupon,
+        params.fiscalDate,
+        params.time,
+        params.operator,
+        params.restrictions
+      )
+    }
+  }
+
+  fun continueTransaction(data: String): Int =
+    traced("continueTransaction", "data=\"$data\"") { clisitef.continueTransaction(data) }
+
+  /** Without coupon, date and time the library reuses the ones from `startTransaction`. */
+  fun finish(params: FinishParams): Int {
+    val full = params.fiscalCoupon.isNotEmpty() && params.fiscalDate.isNotEmpty() && params.time.isNotEmpty()
+    val input = "confirm=${params.confirm} full=$full coupon=${params.fiscalCoupon} " +
+      "date=${params.fiscalDate} time=${params.time} additional=${params.additionalParams}"
+    return traced("finishTransaction", input) {
+      if (!full) return@traced clisitef.finishTransaction(params.confirm)
+      clisitef.finishTransaction(params.confirm, params.fiscalCoupon, params.fiscalDate, params.time, params.additionalParams)
+    }
+  }
+
+  fun abort(continueFlag: Int): Int =
+    traced("abortTransaction", "continueFlag=$continueFlag") { clisitef.abortTransaction(continueFlag) }
+
+  fun pendingCount(fiscalDate: String, fiscalCoupon: String): Int =
+    traced("getQttPendingTransactions", "date=$fiscalDate coupon=$fiscalCoupon") {
+      clisitef.getQttPendingTransactions(fiscalDate, fiscalCoupon)
+    }
+
+  fun submitPending(): Int = traced("submitPendingMessages", "") { clisitef.submitPendingMessages() }
+
+  fun version(): String = traced("getVersion", "") { clisitef.getVersion() }
+
+  fun closePinPad(): Int = traced("closePinPad", "") { clisitef.closePinPad() }
+
+  fun disconnectSitef(): Int {
+    traced("disconnectSitef", "") { clisitef.disconnectSitef() }
+    return 0
+  }
+
+  companion object {
+    private const val TAG = "CliSiTef"
+    // TODO(debug-clisitef): remove.
+    private const val DEBUG_TAG = "CLISITEF_DEBUG"
+    private const val CLSIT = "CLSIT"
+    private val APP_DIR = Regex("DiretorioApp=[^;\\]]*")
+
+    /**
+     * The library keeps pending confirmations and tables under `DiretorioApp`; a wrong
+     * applicationId there loses pending undo messages on restart (seen in the legacy staging APK).
+     */
+    fun withAppDir(params: String, dataDir: String): String {
+      if (dataDir.isEmpty()) return params
+      val entry = "DiretorioApp=$dataDir"
+      if (APP_DIR.containsMatchIn(params)) return params.replace(APP_DIR, Regex.escapeReplacement(entry))
+      val trimmed = params.trim()
+      if (trimmed.isEmpty()) return "[$entry]"
+      if (trimmed.endsWith("]")) return "${trimmed.dropLast(1)};$entry]"
+      return "$trimmed;$entry"
+    }
+
+    /** Idempotent and atomic; a missing or empty asset keeps the current file. */
+    private fun syncClsit(context: Context) {
+      val target = File(context.filesDir, CLSIT)
+      val temp = File(context.filesDir, "$CLSIT.new")
+      try {
+        val shipped = context.assets.open(CLSIT).use { it.readBytes() }
+        // TODO(debug-clisitef): remove.
+        Log.d(DEBUG_TAG, "syncClsit › shipped=${shipped.size}B target=${target.absolutePath} exists=${target.isFile}")
+        if (shipped.isEmpty()) return
+        if (target.isFile && target.readBytes().contentEquals(shipped)) return
+        temp.outputStream().use { out ->
+          out.write(shipped)
+          out.flush()
+          out.fd.sync()
+        }
+        if (!temp.renameTo(target) && !(target.delete() && temp.renameTo(target))) {
+          temp.delete()
+        }
+      } catch (error: Exception) {
+        Log.w(TAG, "CLSIT sync skipped: ${error.message}")
+        temp.delete()
+      }
+    }
+  }
+}

package/android/src/main/java/dev/firespark/payments/clisitef/CliSiTefModule.kt

@@ -0,0 +1,73 @@
+package dev.firespark.payments.clisitef
+
+import expo.modules.kotlin.Promise
+import expo.modules.kotlin.exception.Exceptions
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+class CliSiTefModule : Module() {
+  private val runner = BoundedRunner()
+  private var bridge: CliSiTefBridge? = null
+
+  private fun bridge(): CliSiTefBridge = synchronized(this) {
+    bridge?.let { return it }
+    val context = appContext.reactContext?.applicationContext ?: throw Exceptions.ReactContextLost()
+    // TODO(debug-clisitef): remove.
+    android.util.Log.d("CLISITEF_DEBUG", "module › creating bridge dataDir=${context.applicationInfo.dataDir}")
+    CliSiTefBridge(
+      context,
+      onData = { event -> sendEvent("onData", event.toMap()) },
+      onResult = { stage, code -> sendEvent("onTransactionResult", mapOf("stage" to stage, "resultCode" to code)) }
+    ).also { bridge = it }
+  }
+
+  override fun definition() = ModuleDefinition {
+    Name("CliSiTef")
+
+    Events("onData", "onTransactionResult")
+
+    AsyncFunction("configure") { params: ConfigureParams, promise: Promise ->
+      runner.run("configure", 15_000, promise) { bridge().configure(params) }
+    }
+
+    AsyncFunction("startTransaction") { params: StartParams, promise: Promise ->
+      runner.run("startTransaction", 30_000, promise) { bridge().start(params) }
+    }
+
+    AsyncFunction("continueTransaction") { data: String, promise: Promise ->
+      runner.run("continueTransaction", 0, promise) { bridge().continueTransaction(data) }
+    }
+
+    AsyncFunction("finishTransaction") { params: FinishParams, promise: Promise ->
+      runner.run("finishTransaction", 15_000, promise) { bridge().finish(params) }
+    }
+
+    AsyncFunction("abortTransaction") { continueFlag: Int, promise: Promise ->
+      runner.run("abortTransaction", 15_000, promise, Lane.ABORT) { bridge().abort(continueFlag) }
+    }
+
+    AsyncFunction("getQttPendingTransactions") { fiscalDate: String, fiscalCoupon: String, promise: Promise ->
+      runner.run("getQttPendingTransactions", 15_000, promise) { bridge().pendingCount(fiscalDate, fiscalCoupon) }
+    }
+
+    AsyncFunction("submitPendingMessages") { promise: Promise ->
+      runner.run("submitPendingMessages", 15_000, promise) { bridge().submitPending() }
+    }
+
+    AsyncFunction("getVersion") { promise: Promise ->
+      runner.run("getVersion", 15_000, promise) { bridge().version() }
+    }
+
+    AsyncFunction("closePinPad") { promise: Promise ->
+      runner.run("closePinPad", 10_000, promise, Lane.RECOVERY) { bridge().closePinPad() }
+    }
+
+    AsyncFunction("disconnectSitef") { promise: Promise ->
+      runner.run("disconnectSitef", 10_000, promise, Lane.RECOVERY) { bridge().disconnectSitef() }
+    }
+
+    Function("getHealth") { runner.health(bridge?.appDirectory) }
+
+    OnDestroy { runner.shutdown() }
+  }
+}

package/android/src/main/java/dev/firespark/payments/clisitef/CliSiTefRecords.kt

@@ -0,0 +1,47 @@
+package dev.firespark.payments.clisitef
+
+import expo.modules.kotlin.records.Field
+import expo.modules.kotlin.records.Record
+
+class ConfigureParams : Record {
+  @Field val serverIp: String = ""
+  @Field val storeCode: String = ""
+  @Field val terminalNumber: String = ""
+  @Field val additionalParams: String = ""
+}
+
+class StartParams : Record {
+  @Field val modality: Int = 0
+  @Field val value: String = ""
+  @Field val fiscalCoupon: String = ""
+  @Field val fiscalDate: String = ""
+  @Field val time: String = ""
+  @Field val operator: String = ""
+  @Field val restrictions: String = ""
+}
+
+class FinishParams : Record {
+  @Field val confirm: Int = 0
+  @Field val fiscalCoupon: String = ""
+  @Field val fiscalDate: String = ""
+  @Field val time: String = ""
+  @Field val additionalParams: String = ""
+}
+
+data class DataEvent(
+  val stage: Int,
+  val command: Int,
+  val fieldId: Int,
+  val minLength: Int,
+  val maxLength: Int,
+  val input: String
+) {
+  fun toMap(): Map<String, Any> = mapOf(
+    "stage" to stage,
+    "command" to command,
+    "fieldId" to fieldId,
+    "minLength" to minLength,
+    "maxLength" to maxLength,
+    "input" to input
+  )
+}

package/app.plugin.js

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

package/dist/index.d.mts

@@ -0,0 +1,199 @@
+//#region src/types.d.ts
+type ClisitefConfigureParams = {
+  serverIp: string;
+  storeCode: string;
+  terminalNumber: string;
+  /** `[TipoPinPad=...;ParmsClient=...]`; the native side sets `DiretorioApp`. */
+  additionalParams: string;
+};
+type ClisitefStartParams = {
+  modality: number;
+  /** Amount as SiTef expects it: `"123,45"`. */
+  value: string;
+  fiscalCoupon: string;
+  /** `YYYYMMDD` in the store time zone. */
+  fiscalDate: string;
+  /** `HHMMSS` in the store time zone. */
+  time: string;
+  operator: string;
+  restrictions: string;
+};
+type ClisitefFinishParams = {
+  /** 1 confirms the transaction, 0 undoes it. */
+  confirm: 0 | 1;
+  fiscalCoupon: string;
+  fiscalDate: string;
+  time: string;
+  additionalParams?: string;
+};
+/** One step of the interactive loop: a menu, message or data request. */
+type ClisitefDataEvent = {
+  stage: number;
+  command: number;
+  fieldId: number;
+  minLength: number;
+  maxLength: number;
+  input: string;
+};
+type ClisitefResultEvent = {
+  stage: number;
+  resultCode: number;
+};
+type ClisitefHealth = {
+  consecutiveTimeouts: number;
+  executorReplacements: number;
+  lastTimeoutOperation: string | null;
+  lastCallOperation: string | null;
+  lastCallDurationMs: number;
+  /** `DiretorioApp` the library writes to; `null` until the bridge starts. */
+  appDirectory: string | null;
+};
+type ClisitefEvents = {
+  onData: (event: ClisitefDataEvent) => void;
+  onTransactionResult: (event: ClisitefResultEvent) => void;
+};
+type ClisitefSubscription = {
+  remove: () => void;
+};
+/** Shape of the Expo module registered as `CliSiTef` on Android. */
+type ClisitefNativeModule = {
+  configure: (params: ClisitefConfigureParams) => Promise<number>;
+  startTransaction: (params: ClisitefStartParams) => Promise<number>;
+  continueTransaction: (data: string) => Promise<number>;
+  finishTransaction: (params: ClisitefFinishParams) => Promise<number>;
+  abortTransaction: (continueFlag: number) => Promise<number>;
+  getQttPendingTransactions: (fiscalDate: string, fiscalCoupon: string) => Promise<number>;
+  submitPendingMessages: () => Promise<number>;
+  getVersion: () => Promise<string>;
+  closePinPad: () => Promise<number>;
+  disconnectSitef: () => Promise<number>;
+  getHealth: () => ClisitefHealth;
+  addListener: <E extends keyof ClisitefEvents>(event: E, listener: ClisitefEvents[E]) => ClisitefSubscription;
+};
+//#endregion
+//#region src/client.d.ts
+type ClisitefClientOptions = {
+  /** Extra wait after the native ceiling before the JS side gives up. */
+  graceMs?: number;
+};
+type ClisitefClient = {
+  readonly available: boolean;
+  /** Skips the native call when the config did not change since the last success. */
+  configure: (config: ClisitefConfigureParams) => Promise<number>;
+  /** Forces the next `configure` to reach the native side. */
+  invalidate: () => void;
+  startTransaction: (params: ClisitefStartParams) => Promise<number>;
+  continueTransaction: (data: string) => Promise<number>;
+  finishTransaction: (params: ClisitefFinishParams) => Promise<number>;
+  abortTransaction: (continueFlag: number) => Promise<number>;
+  getQttPendingTransactions: (fiscalDate: string, fiscalCoupon: string) => Promise<number>;
+  submitPendingMessages: () => Promise<number>;
+  getVersion: () => Promise<string>;
+  /** Recovery for a hung library: releases the pinpad without restarting the app. */
+  closePinPad: () => Promise<number>;
+  /** Recovery for a hung library: drops the SiTef connection so a blocked call fails. */
+  disconnectSitef: () => Promise<number>;
+  getHealth: () => ClisitefHealth | null;
+  onData: (listener: ClisitefEvents["onData"]) => ClisitefSubscription;
+  onTransactionResult: (listener: ClisitefEvents["onTransactionResult"]) => ClisitefSubscription;
+};
+declare const createClisitefClient: (native: ClisitefNativeModule | null, options?: ClisitefClientOptions) => ClisitefClient;
+//#endregion
+//#region src/constants.d.ts
+/** `startTransaction` modalities used by the Brazil kiosk. Voucher shares 2 with debit and differs by restrictions. */
+declare const CLISITEF_MODALITY: {
+  readonly DEBIT: 2;
+  readonly CREDIT: 3;
+  readonly VOUCHER: 2;
+  readonly PIX: 122;
+};
+declare const CLISITEF_RESULT: {
+  readonly OK: 0;
+  readonly CONTINUE: 10000;
+};
+declare const CLISITEF_CONFIRM: {
+  readonly CONFIRM: 1;
+  readonly UNDO: 0;
+};
+/** `abortTransaction` flag that closes an unfinished iteration. */
+declare const CLISITEF_ABORT_FLAG = -1;
+declare const CLISITEF_TIMEOUT_CODE = "CLISITEF_TIMEOUT";
+/** Native ceilings per operation; 0 = no ceiling (the loop waits on the customer). */
+declare const CLISITEF_TIMEOUT_MS: {
+  readonly configure: 15000;
+  readonly startTransaction: 30000;
+  readonly continueTransaction: 0;
+  readonly finishTransaction: 15000;
+  readonly abortTransaction: 15000;
+  readonly getQttPendingTransactions: 15000;
+  readonly submitPendingMessages: 15000;
+  readonly getVersion: 15000;
+  readonly closePinPad: 10000;
+  readonly disconnectSitef: 10000;
+};
+type ClisitefOperation = keyof typeof CLISITEF_TIMEOUT_MS;
+/** Extra time the JS backstop waits after the native ceiling before giving up. */
+declare const CLISITEF_JS_GRACE_MS = 5000;
+declare const CLISITEF_DEFAULT_TIME_ZONE = "America/Sao_Paulo";
+declare const CLISITEF_DEFAULT_PINPAD = "ANDROID_USB";
+//#endregion
+//#region src/debug.d.ts
+/** Logs one step: `[CLISITEF_DEBUG] scope › event { data }`. */
+declare const clisitefDebug: (scope: string, event: string, data?: unknown) => void;
+/** Logs the input, the output or the error, and the duration of a call. */
+declare const clisitefDebugCall: <T>(scope: string, input: unknown, call: () => Promise<T>) => Promise<T>;
+//#endregion
+//#region src/errors.d.ts
+declare class ClisitefUnavailableError extends Error {
+  readonly code = "CLISITEF_UNAVAILABLE";
+  constructor();
+}
+type ClisitefTimeoutInfo = {
+  operation: string;
+  timeoutMs: number;
+  consecutiveTimeouts: number | null;
+  executorReplaced: boolean;
+  /** `native`: the Kotlin ceiling fired; `js`: the native call never settled. */
+  source: "native" | "js";
+};
+declare class ClisitefTimeoutError extends Error {
+  readonly code = "CLISITEF_TIMEOUT";
+  readonly info: ClisitefTimeoutInfo;
+  constructor(info: ClisitefTimeoutInfo);
+}
+/** Turns the native `CLISITEF_TIMEOUT` rejection (JSON message) into a typed error. */
+declare const toClisitefTimeout: (error: unknown) => ClisitefTimeoutError | null;
+//#endregion
+//#region src/helpers.d.ts
+/** `123.4` → `"123,40"`. */
+declare const formatClisitefAmount: (amount: number) => string;
+type ClisitefAdditionalParamsInput = {
+  cnpjStore: string;
+  cnpjEnterprise: string;
+  pinpadType?: string;
+};
+/** `[TipoPinPad=ANDROID_USB;ParmsClient=1={cnpjStore};2={cnpjEnterprise}]`. */
+declare const clisitefAdditionalParams: (input: ClisitefAdditionalParamsInput) => string;
+/** Same config ⇒ same signature, so `configure` only runs when something changed. */
+declare const clisitefConfigSignature: (config: ClisitefConfigureParams) => string;
+type ClisitefFiscalDateTime = {
+  fiscalDate: string;
+  time: string;
+};
+/** `YYYYMMDD` / `HHMMSS` in the store time zone (not the device one). */
+declare const clisitefFiscalDateTime: (date?: Date, timeZone?: string) => ClisitefFiscalDateTime;
+type ClisitefMenuOption = {
+  value: string;
+  label: string;
+};
+/**
+ * Command 21 buffer, documented as `"1:Débito;2:Crédito;"`. Falls back to
+ * alternating `"1;Débito;2;Crédito;"` tokens.
+ */
+declare const parseClisitefMenu: (input: string) => ClisitefMenuOption[];
+//#endregion
+//#region src/index.d.ts
+/** Shared client bound to the device's native module; one per app. */
+declare const clisitef: ClisitefClient;
+//#endregion
+export { CLISITEF_ABORT_FLAG, CLISITEF_CONFIRM, CLISITEF_DEFAULT_PINPAD, CLISITEF_DEFAULT_TIME_ZONE, CLISITEF_JS_GRACE_MS, CLISITEF_MODALITY, CLISITEF_RESULT, CLISITEF_TIMEOUT_CODE, CLISITEF_TIMEOUT_MS, ClisitefAdditionalParamsInput, ClisitefClient, ClisitefClientOptions, ClisitefConfigureParams, ClisitefDataEvent, ClisitefEvents, ClisitefFinishParams, ClisitefFiscalDateTime, ClisitefHealth, ClisitefMenuOption, ClisitefNativeModule, ClisitefOperation, ClisitefResultEvent, ClisitefStartParams, ClisitefSubscription, ClisitefTimeoutError, ClisitefTimeoutInfo, ClisitefUnavailableError, clisitef, clisitefAdditionalParams, clisitefConfigSignature, clisitefDebug, clisitefDebugCall, clisitefFiscalDateTime, createClisitefClient, formatClisitefAmount, parseClisitefMenu, toClisitefTimeout };

package/dist/index.mjs

@@ -0,0 +1,312 @@
+import { requireOptionalNativeModule } from "expo";
+//#region src/constants.ts
+/** `startTransaction` modalities used by the Brazil kiosk. Voucher shares 2 with debit and differs by restrictions. */
+const CLISITEF_MODALITY = {
+	DEBIT: 2,
+	CREDIT: 3,
+	VOUCHER: 2,
+	PIX: 122
+};
+const CLISITEF_RESULT = {
+	OK: 0,
+	CONTINUE: 1e4
+};
+const CLISITEF_CONFIRM = {
+	CONFIRM: 1,
+	UNDO: 0
+};
+/** `abortTransaction` flag that closes an unfinished iteration. */
+const CLISITEF_ABORT_FLAG = -1;
+const CLISITEF_TIMEOUT_CODE = "CLISITEF_TIMEOUT";
+/** Native ceilings per operation; 0 = no ceiling (the loop waits on the customer). */
+const CLISITEF_TIMEOUT_MS = {
+	configure: 15e3,
+	startTransaction: 3e4,
+	continueTransaction: 0,
+	finishTransaction: 15e3,
+	abortTransaction: 15e3,
+	getQttPendingTransactions: 15e3,
+	submitPendingMessages: 15e3,
+	getVersion: 15e3,
+	closePinPad: 1e4,
+	disconnectSitef: 1e4
+};
+/** Extra time the JS backstop waits after the native ceiling before giving up. */
+const CLISITEF_JS_GRACE_MS = 5e3;
+const CLISITEF_DEFAULT_TIME_ZONE = "America/Sao_Paulo";
+const CLISITEF_DEFAULT_PINPAD = "ANDROID_USB";
+//#endregion
+//#region src/debug.ts
+const TAG = "[CLISITEF_DEBUG]";
+const elapsed = (startedAt) => Date.now() - startedAt;
+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
+		};
+	}
+	return value;
+};
+/** Logs one step: `[CLISITEF_DEBUG] scope › event { data }`. */
+const clisitefDebug = (scope, event, data) => {
+	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 clisitefDebugCall = async (scope, input, call) => {
+	const startedAt = Date.now();
+	clisitefDebug(scope, "→ in", input);
+	try {
+		const output = await call();
+		const ms = elapsed(startedAt);
+		clisitefDebug(scope, "← out", {
+			output: safe(output),
+			ms
+		});
+		return output;
+	} catch (error) {
+		const ms = elapsed(startedAt);
+		clisitefDebug(scope, "✕ error", {
+			error: safe(error),
+			ms
+		});
+		throw error;
+	}
+};
+//#endregion
+//#region src/errors.ts
+var ClisitefUnavailableError = class extends Error {
+	code = "CLISITEF_UNAVAILABLE";
+	constructor() {
+		super("CliSiTef native module is not available (Android build with the CliSiTef plugin required)");
+		this.name = "ClisitefUnavailableError";
+	}
+};
+var ClisitefTimeoutError = class extends Error {
+	code = CLISITEF_TIMEOUT_CODE;
+	info;
+	constructor(info) {
+		super(`CliSiTef ${info.operation} timed out after ${info.timeoutMs} ms`);
+		this.name = "ClisitefTimeoutError";
+		this.info = info;
+	}
+};
+const asRecord = (value) => {
+	if (typeof value !== "object" || value === null) return null;
+	return value;
+};
+/** Turns the native `CLISITEF_TIMEOUT` rejection (JSON message) into a typed error. */
+const toClisitefTimeout = (error) => {
+	const record = asRecord(error);
+	if (!record || record.code !== "CLISITEF_TIMEOUT") return null;
+	let payload = {};
+	try {
+		payload = asRecord(JSON.parse(String(record.message))) ?? {};
+	} catch {
+		payload = {};
+	}
+	return new ClisitefTimeoutError({
+		operation: typeof payload.operation === "string" ? payload.operation : "unknown",
+		timeoutMs: typeof payload.timeoutMs === "number" ? payload.timeoutMs : 0,
+		consecutiveTimeouts: typeof payload.consecutiveTimeouts === "number" ? payload.consecutiveTimeouts : null,
+		executorReplaced: payload.executorReplaced === true,
+		source: "native"
+	});
+};
+//#endregion
+//#region src/helpers.ts
+/** `123.4` → `"123,40"`. */
+const formatClisitefAmount = (amount) => {
+	if (!Number.isFinite(amount) || amount < 0) throw new RangeError(`Invalid CliSiTef amount: ${amount}`);
+	return amount.toFixed(2).replace(".", ",");
+};
+const digits = (value) => value.replace(/\D/g, "");
+/** `[TipoPinPad=ANDROID_USB;ParmsClient=1={cnpjStore};2={cnpjEnterprise}]`. */
+const clisitefAdditionalParams = (input) => {
+	return `[TipoPinPad=${input.pinpadType ?? "ANDROID_USB"};ParmsClient=1=${digits(input.cnpjStore)};2=${digits(input.cnpjEnterprise)}]`;
+};
+/** Same config ⇒ same signature, so `configure` only runs when something changed. */
+const clisitefConfigSignature = (config) => {
+	const { serverIp, storeCode, terminalNumber, additionalParams } = config;
+	return [
+		serverIp,
+		storeCode,
+		terminalNumber,
+		additionalParams
+	].map((value) => value.trim()).join("|");
+};
+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;
+};
+/** `YYYYMMDD` / `HHMMSS` in the store time zone (not the device one). */
+const clisitefFiscalDateTime = (date = /* @__PURE__ */ new Date(), timeZone = CLISITEF_DEFAULT_TIME_ZONE) => {
+	const parts = Object.fromEntries(formatterFor(timeZone).formatToParts(date).map((part) => [part.type, part.value]));
+	return {
+		fiscalDate: `${parts.year}${parts.month}${parts.day}`,
+		time: `${parts.hour}${parts.minute}${parts.second}`
+	};
+};
+const MENU_ITEM = /^(\d+):(.+)$/;
+/**
+* Command 21 buffer, documented as `"1:Débito;2:Crédito;"`. Falls back to
+* alternating `"1;Débito;2;Crédito;"` tokens.
+*/
+const parseClisitefMenu = (input) => {
+	const tokens = input.split(";").map((token) => token.trim());
+	const options = [];
+	for (const token of tokens) {
+		const match = MENU_ITEM.exec(token);
+		const value = match?.[1];
+		const label = match?.[2]?.trim();
+		if (value && label) options.push({
+			value,
+			label
+		});
+	}
+	if (options.length > 0) return options;
+	for (let i = 0; i + 1 < tokens.length; i += 2) {
+		const value = tokens[i];
+		const label = tokens[i + 1];
+		if (value && label) options.push({
+			value,
+			label
+		});
+	}
+	return options;
+};
+//#endregion
+//#region src/client.ts
+const createClisitefClient = (native, options = {}) => {
+	const graceMs = options.graceMs ?? 5e3;
+	let signature = null;
+	const requireNative = () => {
+		if (!native) throw new ClisitefUnavailableError();
+		return native;
+	};
+	const bounded = async (operation, call, input) => {
+		return clisitefDebugCall(`client.${operation}`, input, () => boundedCall(operation, call));
+	};
+	const boundedCall = async (operation, call) => {
+		const module = requireNative();
+		const ceiling = CLISITEF_TIMEOUT_MS[operation];
+		let timer;
+		const backstop = new Promise((_, reject) => {
+			if (ceiling === 0) return;
+			const timeoutMs = ceiling + graceMs;
+			const info = {
+				operation,
+				timeoutMs,
+				consecutiveTimeouts: null,
+				executorReplaced: false,
+				source: "js"
+			};
+			timer = setTimeout(() => reject(new ClisitefTimeoutError(info)), timeoutMs);
+		});
+		try {
+			return await Promise.race([call(module), backstop]);
+		} catch (error) {
+			const timeout = error instanceof ClisitefTimeoutError ? error : toClisitefTimeout(error);
+			if (!timeout) throw error;
+			clisitefDebug(`client.${operation}`, "timeout", timeout.info);
+			signature = null;
+			throw timeout;
+		} finally {
+			clearTimeout(timer);
+		}
+	};
+	const configure = async (config) => {
+		const next = clisitefConfigSignature(config);
+		if (next === signature) {
+			clisitefDebug("client.configure", "skipped (same config)", config);
+			return 0;
+		}
+		const call = (module) => module.configure(config);
+		const code = await bounded("configure", call, config);
+		signature = code === 0 ? next : null;
+		return code;
+	};
+	const listen = (event, listener) => {
+		const logged = ((payload) => {
+			clisitefDebug(`client.event.${event}`, "← native", payload);
+			listener(payload);
+		});
+		clisitefDebug(`client.event.${event}`, "subscribe");
+		const subscription = requireNative().addListener(event, logged);
+		return { remove: () => {
+			clisitefDebug(`client.event.${event}`, "unsubscribe");
+			subscription.remove();
+		} };
+	};
+	return {
+		available: native !== null,
+		configure,
+		invalidate: () => {
+			clisitefDebug("client.invalidate", "signature cleared");
+			signature = null;
+		},
+		startTransaction: (params) => {
+			const call = (m) => m.startTransaction(params);
+			return bounded("startTransaction", call, params);
+		},
+		continueTransaction: (data) => {
+			const call = (m) => m.continueTransaction(data);
+			return bounded("continueTransaction", call, { data });
+		},
+		finishTransaction: (params) => {
+			const call = (m) => m.finishTransaction(params);
+			return bounded("finishTransaction", call, params);
+		},
+		abortTransaction: (flag) => {
+			const call = (m) => m.abortTransaction(flag);
+			return bounded("abortTransaction", call, { continueFlag: flag });
+		},
+		getQttPendingTransactions: (date, coupon) => {
+			const call = (m) => {
+				return m.getQttPendingTransactions(date, coupon);
+			};
+			return bounded("getQttPendingTransactions", call, {
+				fiscalDate: date,
+				fiscalCoupon: coupon
+			});
+		},
+		submitPendingMessages: () => {
+			return bounded("submitPendingMessages", (m) => m.submitPendingMessages());
+		},
+		getVersion: () => bounded("getVersion", (module) => module.getVersion()),
+		closePinPad: () => bounded("closePinPad", (module) => module.closePinPad()),
+		disconnectSitef: () => bounded("disconnectSitef", (module) => module.disconnectSitef()),
+		getHealth: () => {
+			const health = native?.getHealth() ?? null;
+			clisitefDebug("client.getHealth", "← out", health);
+			return health;
+		},
+		onData: (listener) => listen("onData", listener),
+		onTransactionResult: (listener) => listen("onTransactionResult", listener)
+	};
+};
+//#endregion
+//#region src/index.ts
+/** Shared client bound to the device's native module; one per app. */
+const clisitef = createClisitefClient(requireOptionalNativeModule("CliSiTef"));
+//#endregion
+export { CLISITEF_ABORT_FLAG, CLISITEF_CONFIRM, CLISITEF_DEFAULT_PINPAD, CLISITEF_DEFAULT_TIME_ZONE, CLISITEF_JS_GRACE_MS, CLISITEF_MODALITY, CLISITEF_RESULT, CLISITEF_TIMEOUT_CODE, CLISITEF_TIMEOUT_MS, ClisitefTimeoutError, ClisitefUnavailableError, clisitef, clisitefAdditionalParams, clisitefConfigSignature, clisitefDebug, clisitefDebugCall, clisitefFiscalDateTime, createClisitefClient, formatClisitefAmount, parseClisitefMenu, toClisitefTimeout };

package/expo-module.config.json

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

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@fire-spark/payments-clisitef-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.7.1",
+  "description": "Fire Spark native client for CliSiTef (Software Express) on Android: SiTef server and pinpad bridge shared by the CliSiTef 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/CLSIT

@@ -0,0 +1,21 @@
+[CliSiTef]
+HabilitaTrace=1
+TraceRotativo=20
+DiretorioTrace=./files
+
+[CliSiTefI]
+HabilitaTrace=1
+TraceRotativo=20
+DiretorioTrace=./files
+
+[PinPad]
+HabilitaTrace=1
+
+[Geral]
+TransacoesAdicionaisHabilitadas = 7;8;3919;20;21;22
+
+[SiTef]
+TempoEsperaConexao=300
+TempoAdicionalEspera=1200
+TempoEsperaDesfazimento=30
+TempoEsperaConfirmacao=30

package/plugin/withClisitef.cjs

@@ -0,0 +1,94 @@
+const {
+  AndroidConfig,
+  withAppBuildGradle,
+  withDangerousMod
+} = require("expo/config-plugins");
+const fs = require("fs");
+const path = require("path");
+
+const JAR = "clisitef-android.jar";
+const CLSIT = "CLSIT";
+const DEFAULT_CLSIT = path.join(__dirname, CLSIT);
+const MARKER = "// @fire-spark/payments-clisitef-client";
+
+const copy = (from, to) => {
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  fs.copyFileSync(from, to);
+};
+
+/**
+ * Expected layout of `binariesDir` (per environment, never committed):
+ *   clisitef-android.jar
+ *   jniLibs/<abi>/*.so   (libclisitef, libcrypto, libgsurf_rsa, libjSerialComm, libssl, libtlswnb)
+ *   CLSIT                (optional; defaults to the one shipped with this package)
+ */
+const withClisitefBinaries = (config, { binariesDir }) =>
+  withDangerousMod(config, [
+    "android",
+    async cfg => {
+      const source = path.resolve(cfg.modRequest.projectRoot, binariesDir);
+      const app = path.join(cfg.modRequest.platformProjectRoot, "app");
+      const jar = path.join(source, JAR);
+      if (!fs.existsSync(jar)) {
+        throw new Error(`[clisitef] missing ${jar}; set binariesDir to the CliSiTef files of this environment`);
+      }
+      copy(jar, path.join(app, "libs", JAR));
+      const clsit = path.join(source, CLSIT);
+      copy(fs.existsSync(clsit) ? clsit : DEFAULT_CLSIT, path.join(app, "src/main/assets", CLSIT));
+      const jniLibs = path.join(source, "jniLibs");
+      const libs = fs.existsSync(jniLibs)
+        ? fs.readdirSync(jniLibs, { recursive: true }).filter(file => String(file).endsWith(".so"))
+        : [];
+      if (!libs.some(file => path.basename(String(file)) === "libclisitef.so")) {
+        throw new Error(`[clisitef] no libclisitef.so found under ${jniLibs}/<abi>/`);
+      }
+      for (const file of libs) {
+        copy(path.join(jniLibs, String(file)), path.join(app, "src/main/jniLibs", String(file)));
+      }
+      return cfg;
+    }
+  ]);
+
+// useLegacyPackaging: Android 14+ does not load libclisitef.so from a compressed APK.
+const gradleBlock = `
+${MARKER}
+android {
+  packagingOptions {
+    jniLibs {
+      useLegacyPackaging true
+      keepDebugSymbols += ["**/libclisitef.so"]
+    }
+  }
+}
+dependencies {
+  implementation files("libs/${JAR}")
+}
+`;
+
+const withClisitefGradle = config =>
+  withAppBuildGradle(config, cfg => {
+    if (!cfg.modResults.contents.includes(MARKER)) {
+      cfg.modResults.contents += gradleBlock;
+    }
+    return cfg;
+  });
+
+const PERMISSIONS = [
+  "android.permission.INTERNET",
+  "android.permission.BLUETOOTH",
+  "android.permission.BLUETOOTH_ADMIN",
+  "android.permission.BLUETOOTH_SCAN",
+  "android.permission.BLUETOOTH_CONNECT"
+];
+
+/** @param {{ binariesDir: string }} options */
+const withClisitef = (config, options = {}) => {
+  if (!options.binariesDir) {
+    throw new Error("[clisitef] the plugin needs { binariesDir }");
+  }
+  config = AndroidConfig.Permissions.withPermissions(config, PERMISSIONS);
+  config = withClisitefBinaries(config, options);
+  return withClisitefGradle(config);
+};
+
+module.exports = withClisitef;

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.