@dodicandra/minesec-rn 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-present 650 Industries, Inc. (aka Expo)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,444 @@
+# @dodicandra/minesec-rn
+
+Expo Native Module (Android) untuk **MineSec Headless SoftPOS SDK** — menerima pembayaran kartu contactless (Tap to Phone) langsung dari aplikasi React Native / Expo tanpa hardware EDC tambahan.
+
+Module ini membungkus MineSec Headless SDK v1 (`com.theminesec.sdk:headless`) dengan API JavaScript yang sederhana dan fully-typed, plus **Expo Config Plugin** yang mengurus seluruh konfigurasi native (AndroidManifest, Gradle, Maven repository, file lisensi) secara otomatis saat `expo prebuild`.
+
+> ⚠️ **Android only.** SoftPOS membutuhkan NFC dan MineSec SDK hanya tersedia untuk Android (minSdk 30 / Android 11+). Di iOS dan web, module tidak melakukan apa-apa.
+
+---
+
+## Daftar Isi
+
+- [Prasyarat](#prasyarat)
+- [Instalasi](#instalasi)
+- [Konfigurasi](#konfigurasi)
+  - [1. Config plugin di app.json](#1-config-plugin-di-appjson)
+  - [2. Kredensial Maven MineSec](#2-kredensial-maven-minesec)
+  - [3. File lisensi](#3-file-lisensi)
+  - [4. Prebuild & build](#4-prebuild--build)
+- [Cara Penggunaan](#cara-penggunaan)
+  - [Alur dasar](#alur-dasar)
+  - [Inisialisasi SDK](#inisialisasi-sdk)
+  - [Initial setup (sekali per instalasi)](#initial-setup-sekali-per-instalasi)
+  - [Transaksi SALE (tap kartu NFC)](#transaksi-sale-tap-kartu-nfc)
+  - [Void, Refund, Adjust, Auth Completion](#void-refund-adjust-auth-completion)
+  - [Query transaksi](#query-transaksi)
+  - [Penanganan error](#penanganan-error)
+- [Referensi API](#referensi-api)
+- [Referensi Tipe](#referensi-tipe)
+- [Apa yang Dilakukan Config Plugin](#apa-yang-dilakukan-config-plugin)
+- [Staging vs Production](#staging-vs-production)
+- [Troubleshooting](#troubleshooting)
+- [Menjalankan Contoh (example/)](#menjalankan-contoh-example)
+- [Lisensi](#lisensi)
+
+---
+
+## Prasyarat
+
+Sebelum memakai module ini kamu membutuhkan:
+
+| Kebutuhan | Keterangan |
+|---|---|
+| Akun MineSec | Kredensial Maven (username + token) untuk mengunduh SDK dari GitHub Packages `TheMinesec/ms-registry-client` |
+| File lisensi `.license` | Diterbitkan MineSec, terikat ke `applicationId` aplikasi kamu. Lisensi stage ≠ lisensi live |
+| Profile ID | ID profil pembayaran (`prof_...`) dari backend MineSec untuk routing transaksi |
+| Expo SDK 52+ | Proyek Expo dengan development build (module ini **tidak jalan di Expo Go**) |
+| Perangkat Android | Android 11+ (API 30) dengan NFC, perangkat fisik (bukan emulator) untuk tap kartu |
+
+## Instalasi
+
+```sh
+npx expo install @dodicandra/minesec-rn
+```
+
+atau dengan package manager langsung:
+
+```sh
+npm install @dodicandra/minesec-rn
+# atau
+yarn add @dodicandra/minesec-rn
+```
+
+Karena berisi kode native, aplikasi harus di-build ulang sebagai [development build](https://docs.expo.dev/develop/development-builds/introduction/) setelah instalasi — Expo Go tidak mendukung native module pihak ketiga.
+
+## Konfigurasi
+
+### 1. Config plugin di app.json
+
+Daftarkan plugin di `app.json` / `app.config.js`:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "@dodicandra/minesec-rn",
+        {
+          "enableNfc": true,
+          "licenseFileName": "mnc.license"
+        }
+      ]
+    ]
+  }
+}
+```
+
+Opsi plugin yang tersedia:
+
+| Opsi | Tipe | Default | Keterangan |
+|---|---|---|---|
+| `enableNfc` | `boolean` | `true` | Menambahkan permission `android.permission.NFC` dan feature `android.hardware.nfc` (required). Set `false` jika konflik dengan library lain |
+| `licenseFileName` | `string` | — | Nama file lisensi di **project root**; otomatis dicopy ke `android/app/src/main/assets/` saat prebuild |
+| `username` | `string` | — | Maven username MineSec; ditulis ke `gradle.properties`. **Hanya untuk development** — lihat catatan keamanan di bawah |
+| `usertoken` | `string` | — | Maven token MineSec; ditulis ke `gradle.properties`. **Hanya untuk development** |
+
+### 2. Kredensial Maven MineSec
+
+SDK native diunduh dari GitHub Packages milik MineSec, sehingga Gradle butuh kredensial. Ada tiga cara, urut dari yang paling direkomendasikan:
+
+**a. Environment variables (direkomendasikan untuk CI/production):**
+
+```sh
+export MINESEC_MAVEN_USER="username-anda"
+export MINESEC_MAVEN_TOKEN="ghp_xxxxxxxxxxxx"
+```
+
+**b. Global `~/.gradle/gradle.properties` (direkomendasikan untuk mesin development):**
+
+```properties
+username=username-anda
+usertoken=ghp_xxxxxxxxxxxx
+```
+
+**c. Opsi plugin `username`/`usertoken` di `app.json`:**
+
+Praktis untuk eksperimen cepat, tapi **jangan commit kredensial ke repository**. `app.json` biasanya ikut ter-commit — gunakan `app.config.js` yang membaca dari env var jika tetap ingin memakai jalur ini:
+
+```js
+// app.config.js
+export default {
+  expo: {
+    plugins: [
+      [
+        '@dodicandra/minesec-rn',
+        {
+          licenseFileName: 'mnc.license',
+          username: process.env.MINESEC_MAVEN_USER,
+          usertoken: process.env.MINESEC_MAVEN_TOKEN,
+        },
+      ],
+    ],
+  },
+};
+```
+
+### 3. File lisensi
+
+Letakkan file `.license` dari MineSec di **root proyek aplikasi** (sejajar dengan `app.json`):
+
+```
+my-app/
+├── app.json
+├── mnc.license        ← di sini
+├── package.json
+└── ...
+```
+
+Saat prebuild, plugin akan menyalinnya ke `android/app/src/main/assets/`. Nama file inilah yang nanti kamu berikan ke `initSoftPos()`.
+
+> Penting: lisensi terikat ke `applicationId` **dan** environment (stage/live). Lisensi test/stage tidak akan valid di SDK varian live, dan sebaliknya (error `61001`).
+
+### 4. Prebuild & build
+
+```sh
+npx expo prebuild --platform android
+npx expo run:android
+```
+
+atau dengan EAS:
+
+```sh
+eas build --platform android --profile development
+```
+
+## Cara Penggunaan
+
+### Alur dasar
+
+```
+App launch ──▶ initSoftPos()          (setiap kali app dibuka)
+                    │
+Instalasi baru ──▶ initialSetup()     (cukup sekali per instalasi)
+                    │
+Pembayaran   ──▶ launchTransaction()  (membuka UI tap kartu NFC)
+                    │
+Manajemen    ──▶ createAction()       (void/refund/adjust — tanpa UI)
+                 getTransaction()     (query status transaksi)
+```
+
+### Inisialisasi SDK
+
+Panggil `initSoftPos()` setiap kali aplikasi dibuka, misalnya di komponen root:
+
+```tsx
+import Minesecrn from '@dodicandra/minesec-rn';
+
+const result = await Minesecrn.initSoftPos('mnc.license');
+
+if (result.success) {
+  console.log('SDK siap:', result.value.sdkVersion, result.value.sdkId);
+} else {
+  console.error(`Init gagal [${result.code}]: ${result.message}`);
+}
+```
+
+### Initial setup (sekali per instalasi)
+
+Setelah init berhasil, jalankan `initialSetup()` **satu kali per instalasi aplikasi**. Proses ini mengunduh parameter EMV, CAPK, konfigurasi terminal, dan meng-inject key dari server MineSec:
+
+```ts
+// withTestCapk: true untuk environment staging/development
+const setup = await Minesecrn.initialSetup(true);
+
+if (setup.sdkRes.success) {
+  console.log('Setup selesai');
+} else {
+  console.error('Setup gagal:', setup.sdkRes);
+}
+```
+
+Simpan flag (misalnya di AsyncStorage) agar setup tidak diulang di launch berikutnya.
+
+### Transaksi SALE (tap kartu NFC)
+
+`launchTransaction()` membuka activity native full-screen untuk tap kartu, lalu resolve dengan hasil transaksi:
+
+```ts
+const result = await Minesecrn.launchTransaction({
+  type: 'ActionNew',
+  tranType: 'SALE',
+  amount: { value: '10000', currencyCode: 'IDR' },
+  profileId: 'prof_01XXXXXXXXXXXXXXXXXXXXXXXX',
+  primaryTid: '30157001',
+  posReference: `POS-${Date.now()}`,
+  description: 'Pembelian kopi',
+});
+
+if (result.success) {
+  const tx = result.value;
+  console.log(`${tx.status} — ${tx.paymentMethod} ${tx.accountMasked}`);
+  console.log('tranId:', tx.id, 'approval:', tx.approvalCode);
+} else {
+  console.error(`Transaksi gagal [${result.code}]: ${result.message}`);
+}
+```
+
+`tranType` yang didukung: `'SALE'`, `'AUTH'` (pre-authorization), `'REFUND'`.
+
+Field opsional lain di `ActionNew`: `cvmSignatureMode` (`'ELECTRONIC_SIGNATURE'` | `'SIGN_ON_PAPER'`), `tapToOwnDevice`, `installmentPlan`, dan `extra` (metadata key-value).
+
+### Void, Refund, Adjust, Auth Completion
+
+Aksi terhadap transaksi yang sudah ada tidak butuh tap kartu. Bisa lewat `createAction()` (background, tanpa UI) atau `launchTransaction()` (dengan UI):
+
+```ts
+// Void — membatalkan transaksi sebelum settlement
+await Minesecrn.createAction({
+  type: 'ActionVoid',
+  tranId: 'tran_01XXXXXXXXXXXXXXXXXXXXXXXX',
+});
+
+// Linked refund — refund tanpa tap ulang (hanya gateway MPGS)
+await Minesecrn.createAction({
+  type: 'ActionLinkedRefund',
+  tranId: 'tran_01XXX...',
+  amount: { value: '5000', currencyCode: 'IDR' }, // omit = refund penuh
+});
+
+// Adjust — ubah jumlah (tip / incremental auth)
+await Minesecrn.createAction({
+  type: 'ActionAdjust',
+  tranId: 'tran_01XXX...',
+  amount: { value: '12000', currencyCode: 'IDR' }, // total baru
+});
+
+// Auth completion — capture transaksi pre-authorized
+await Minesecrn.createAction({
+  type: 'ActionAuthComp',
+  tranId: 'tran_01XXX...',
+  amount: { value: '10000', currencyCode: 'IDR' },
+});
+```
+
+### Query transaksi
+
+```ts
+// Berdasarkan tranId (prefix "tran_")
+const byId = await Minesecrn.getTransaction('tranId', 'tran_01XXX...');
+
+// Atau berdasarkan posReference milik kamu sendiri
+const byRef = await Minesecrn.getTransaction('posReference', 'POS-1720000000000');
+```
+
+### Penanganan error
+
+Semua method mengembalikan `MinesecResult<T>` — discriminated union yang memaksa pengecekan `success` sebelum mengakses data:
+
+```ts
+const result = await Minesecrn.launchTransaction(request);
+
+if (result.success) {
+  // result.value: Transaction — aman diakses
+} else {
+  // result.code: number     — kode error MineSec
+  // result.message: string  — pesan error
+  // result.contextual?: string
+  // result.extra?: Record<string, string>
+}
+```
+
+Kode error yang umum ditemui:
+
+| Kode | Arti | Solusi |
+|---|---|---|
+| `41002` | Cannot get payment profile | Cek `profileId` valid dan profil server cocok dengan versi SDK |
+| `41100` | License file tidak ditemukan | Nama file di `initSoftPos()` harus sama persis dengan file di assets |
+| `60112` | Key attestation gagal | Varian SDK (stage/live) tidak cocok dengan environment server |
+| `61001` | License tidak valid | Lisensi untuk produk/environment berbeda (mis. lisensi v2 dipakai di SDK v1, atau stage vs live) |
+
+## Referensi API
+
+Import default adalah instance module, siap pakai:
+
+```ts
+import Minesecrn from '@dodicandra/minesec-rn';
+```
+
+| Method | Signature | Keterangan |
+|---|---|---|
+| `initSoftPos` | `(licenseFileName: string) => Promise<MinesecResult<SdkInitResult>>` | Inisialisasi SDK. Wajib dipanggil setiap app launch, sebelum method lain |
+| `initialSetup` | `(withTestCapk?: boolean) => Promise<SetupResult>` | Download EMV params, CAPK, terminal config, inject keys. Sekali per instalasi. `withTestCapk: true` untuk staging |
+| `launchTransaction` | `(request: PoiRequest) => Promise<MinesecResult<Transaction>>` | Membuka UI native (NFC tap untuk `ActionNew`). Mendukung semua tipe `PoiRequest` |
+| `createAction` | `(request: PoiRequestBackground) => Promise<MinesecResult<Transaction>>` | Eksekusi aksi background tanpa UI — semua tipe kecuali `ActionNew` |
+| `getTransaction` | `(refType: 'tranId' \| 'posReference', refValue: string) => Promise<MinesecResult<Transaction>>` | Query transaksi berdasarkan referensi |
+
+## Referensi Tipe
+
+Semua tipe di-export dari package:
+
+```ts
+import type {
+  Amount,
+  TranType,
+  CvmSignatureMode,
+  PoiRequest,
+  PoiRequestActionNew,
+  PoiRequestActionVoid,
+  PoiRequestActionLinkedRefund,
+  PoiRequestActionAdjust,
+  PoiRequestActionAuthComp,
+  PoiRequestBackground,
+  TransactionReferenceType,
+  MinesecResult,
+  SdkInitResult,
+  SetupResult,
+  Transaction,
+} from '@dodicandra/minesec-rn';
+```
+
+Tipe-tipe kunci:
+
+```ts
+type Amount = {
+  value: string;        // desimal string, mis. "10000" atau "1.00"
+  currencyCode: string; // ISO 4217, mis. "IDR", "HKD", "USD"
+};
+
+type MinesecResult<T> =
+  | { success: true; value: T }
+  | { success: false; code: number; message: string; contextual?: string; extra?: Record<string, string> };
+
+type Transaction = {
+  id: string;                    // "tran_..."
+  status: string | null;         // mis. "APPROVED"
+  tranType: string | null;
+  amount: Amount | null;
+  posReference: string | null;
+  approvalCode: string | null;
+  paymentMethod: string | null;  // "VISA", "MASTERCARD", dst.
+  accountMasked: string | null;  // nomor kartu tersamar
+  rrn: string | null;
+  batchNo: string | null;
+  createdAt: string | null;
+  updatedAt: string | null;
+};
+```
+
+## Apa yang Dilakukan Config Plugin
+
+Saat `expo prebuild`, plugin `@dodicandra/minesec-rn` otomatis:
+
+1. **AndroidManifest** — menambahkan permission `INTERNET` (+ `NFC` dan feature `android.hardware.nfc` jika `enableNfc`), serta mendaftarkan `MinesecrnHeadlessActivity` dengan `launchMode="singleTask"`.
+2. **Root `build.gradle`** — meng-inject Maven repository MineSec (`maven.pkg.github.com/TheMinesec/ms-registry-client`) lengkap dengan kredensial dari gradle properties / env vars, dan membersihkan blok repository lama jika ada.
+3. **App `build.gradle`** — memastikan `minSdkVersion >= 30` dan menambahkan packaging exclusions `META-INF` yang dibutuhkan SDK.
+4. **`gradle.properties`** — menulis `username`/`usertoken` jika diberikan lewat opsi plugin.
+5. **License** — menyalin file lisensi dari project root ke `android/app/src/main/assets/`.
+
+Semua langkah idempoten — aman menjalankan prebuild berkali-kali.
+
+## Staging vs Production
+
+Module memakai dua varian dependency SDK sesuai build type:
+
+```groovy
+debugImplementation   'com.theminesec.sdk:headless-stage:1.2.57'  // server staging
+releaseImplementation 'com.theminesec.sdk:headless:1.2.57'        // server live
+```
+
+Konsekuensinya:
+
+- **Debug build** terhubung ke server **staging** MineSec → gunakan lisensi test/stage dan `initialSetup(true)`.
+- **Release build** terhubung ke server **live** → gunakan lisensi production dan `initialSetup(false)`.
+- Lisensi, profile ID, dan varian SDK harus berasal dari environment yang **sama** — kombinasi silang menghasilkan error `60112`/`61001`.
+
+## Troubleshooting
+
+**Build gagal: `Could not resolve com.theminesec.sdk:headless...`**
+Kredensial Maven tidak terbaca. Cek env var `MINESEC_MAVEN_USER`/`MINESEC_MAVEN_TOKEN` atau `~/.gradle/gradle.properties`, lalu jalankan ulang prebuild.
+
+**Error `41100` saat `initSoftPos()`**
+Nama file lisensi tidak cocok. Pastikan `licenseFileName` di `app.json`, nama file di project root, dan argumen `initSoftPos()` ketiganya identik, lalu prebuild ulang agar file tercopy ke assets.
+
+**Error `61001` (invalid license)**
+Lisensi tidak cocok dengan varian SDK atau environment. Lisensi stage hanya untuk debug build (`headless-stage`), lisensi live hanya untuk release build.
+
+**Error `60112` (key attestation)**
+Aplikasi debug menghubungi server live atau sebaliknya. Pastikan varian SDK sesuai environment lisensi.
+
+**Module tidak ditemukan / `Cannot find native module 'Minesecrn'`**
+Kamu menjalankan di Expo Go, atau belum rebuild setelah instalasi. Jalankan `npx expo prebuild && npx expo run:android`.
+
+**NFC tidak merespons saat tap**
+Gunakan perangkat fisik dengan NFC aktif — emulator tidak mendukung NFC. Cek juga NFC di system settings.
+
+## Menjalankan Contoh (example/)
+
+Repo ini menyertakan aplikasi contoh lengkap di [`example/`](example/):
+
+```sh
+cd example
+yarn install
+# letakkan file lisensi di example/ sesuai app.json
+npx expo prebuild --platform android
+npx expo run:android
+```
+
+Aplikasi contoh mendemonstrasikan seluruh alur: init → setup → SALE → void → query. Lihat [`example/App.tsx`](example/App.tsx).
+
+## Lisensi
+
+MIT © [dodicandra](https://github.com/dodicandra)
+
+> Catatan: MineSec SDK sendiri adalah software proprietary milik [MineSec](https://theminesec.com). Package ini hanya bridge — kamu tetap membutuhkan perjanjian dan lisensi resmi dari MineSec untuk memakainya.

package/android/build.gradle

@@ -0,0 +1,54 @@
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'expo.modules.minesecrn'
+version = '0.1.0'
+
+android {
+  namespace "expo.modules.minesecrn"
+  defaultConfig {
+    minSdk 30
+    versionCode 1
+    versionName "0.1.0"
+  }
+  packaging {
+    resources {
+      excludes += [
+        "/META-INF/{AL2.0,LGPL2.1}",
+        "META-INF/LICENSE*",
+        "META-INF/NOTICE*",
+        "META-INF/DEPENDENCIES",
+        "*.kotlin_module",
+        "META-INF/versions/9/previous-compilation-data.bin"
+      ]
+    }
+  }
+  lintOptions {
+    abortOnError false
+  }
+}
+
+repositories {
+  maven {
+    url = uri("https://maven.pkg.github.com/TheMinesec/ms-registry-client")
+    credentials {
+      username = (findProperty("username") ?: System.getenv("MINESEC_MAVEN_USER") ?: "").toString()
+      password = (findProperty("usertoken") ?: System.getenv("MINESEC_MAVEN_TOKEN") ?: "").toString()
+    }
+    content {
+      includeGroupByRegex "com\\.theminesec\\..*"
+    }
+  }
+}
+
+dependencies {
+  // Varian SDK harus cocok dengan environment license yang dipakai:
+  // headless-stage = server staging (license test/stage), headless = live.
+  debugImplementation 'com.theminesec.sdk:headless-stage:1.2.57'
+  releaseImplementation 'com.theminesec.sdk:headless:1.2.57'
+  implementation 'androidx.activity:activity-ktx:1.8.2'
+  implementation 'org.jetbrains.kotlinx:kotlinx-datetime:0.6.1'
+  implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,12 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.NFC" />
+  <uses-permission android:name="android.permission.INTERNET" />
+  <uses-feature android:name="android.hardware.nfc" android:required="true" />
+
+  <application>
+    <activity
+      android:name=".MinesecrnHeadlessActivity"
+      android:exported="false"
+      android:launchMode="singleTask" />
+  </application>
+</manifest>

package/android/src/main/java/expo/modules/minesecrn/MinesecrnHeadlessActivity.kt

@@ -0,0 +1,5 @@
+package expo.modules.minesecrn
+
+import com.theminesec.sdk.headless.HeadlessActivity
+
+class MinesecrnHeadlessActivity : HeadlessActivity()

package/android/src/main/java/expo/modules/minesecrn/MinesecrnModule.kt

@@ -0,0 +1,87 @@
+package expo.modules.minesecrn
+
+import android.app.Application
+import com.theminesec.sdk.headless.HeadlessActivity
+import com.theminesec.sdk.headless.HeadlessService
+import com.theminesec.sdk.headless.HeadlessSetup
+import com.theminesec.sdk.headless.model.WrappedResult
+import com.theminesec.lib.dto.poi.Referencable
+import expo.modules.kotlin.Promise
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+import kotlinx.coroutines.runBlocking
+
+class MinesecrnModule : Module() {
+  companion object {
+    const val REQ_TRANSACTION = 42001
+  }
+
+  private var pendingPromise: Promise? = null
+
+  override fun definition() = ModuleDefinition {
+    Name("Minesecrn")
+
+    AsyncFunction("initSoftPos") { licenseFileName: String ->
+      val app = appContext.reactContext!!.applicationContext as Application
+      runBlocking { HeadlessSetup.initSoftPos(app, licenseFileName) }.toResultMap()
+    }
+
+    AsyncFunction("initialSetup") { withTestCapk: Boolean ->
+      val ctx = appContext.reactContext!!
+      runBlocking {
+        HeadlessSetup.initialSetup(ctx) { this.withTestCapk = withTestCapk }
+      }.toSetupResultMap()
+    }
+
+    AsyncFunction("launchTransaction") { request: Map<String, Any?>, promise: Promise ->
+      val activity = appContext.currentActivity
+        ?: return@AsyncFunction promise.reject("NO_ACTIVITY", "No current activity available", null)
+      try {
+        val poiRequest = PoiRequestMapper.toPoiRequest(request)
+        pendingPromise = promise
+        val contract = HeadlessActivity.contract(MinesecrnHeadlessActivity::class.java)
+        activity.startActivityForResult(
+          contract.createIntent(activity, poiRequest),
+          REQ_TRANSACTION
+        )
+      } catch (e: IllegalArgumentException) {
+        promise.reject("INVALID_REQUEST", e.message ?: "Invalid launchTransaction request", e)
+      } catch (e: Exception) {
+        pendingPromise = null
+        promise.reject("LAUNCH_TRANSACTION_ERROR", e.message ?: "Failed to launch transaction", e)
+      }
+    }
+
+    OnActivityResult { _, payload ->
+      if (payload.requestCode != REQ_TRANSACTION) return@OnActivityResult
+      val contract = HeadlessActivity.contract(MinesecrnHeadlessActivity::class.java)
+      val result = contract.parseResult(payload.resultCode, payload.data)
+      val p = pendingPromise.also { pendingPromise = null }
+      when (result) {
+        is WrappedResult.Success<*>,
+        is WrappedResult.Failure -> p?.resolve(result.toResultMap())
+        null -> p?.reject("NULL_RESULT", "No result returned from HeadlessActivity", null)
+      }
+    }
+
+    AsyncFunction("createAction") { request: Map<String, Any?> ->
+      val poiRequest = PoiRequestMapper.toServiceRequest(request)
+      runBlocking { HeadlessService.createAction(poiRequest) }.fold(
+        onSuccess = { mapOf("success" to true, "value" to it.toMap()) },
+        onFailure = { mapOf("success" to false, "code" to -1, "message" to (it.message ?: "Unknown error")) }
+      )
+    }
+
+    AsyncFunction("getTransaction") { refType: String, refValue: String ->
+      val ref = when (refType) {
+        "tranId" -> Referencable.TranId(refValue)
+        "posReference" -> Referencable.PosReference(refValue)
+        else -> throw IllegalArgumentException("Unknown reference type: $refType. Use 'tranId' or 'posReference'")
+      }
+      runBlocking { HeadlessService.getTransaction(ref) }.fold(
+        onSuccess = { mapOf("success" to true, "value" to it.toMap()) },
+        onFailure = { mapOf("success" to false, "code" to -1, "message" to (it.message ?: "Unknown error")) }
+      )
+    }
+  }
+}