halo-sdk-react-native 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to `halo-sdk-react-native` will be documented here.
+
+---
+
+## [1.0.2] - 2026-03-03
+
+### Fixed
+- Changed Halo SDK dependency declaration from `compileOnly` to `api` in `build.gradle` so it is exposed transitively to host apps. This prevents a `NoClassDefFoundError: HaloSDK` crash on launch,  host apps no longer need to add the Halo SDK as a direct dependency.
+
+### Documentation
+- Updated README to remove the now-unnecessary manual Halo SDK runtime dependency step
+- Fixed incorrect `resultType` check in code examples (`'success'`-> `'Initialized'`)
+- Added Result Types reference table for `HaloInitializationResult` and `HaloTransactionResult`
+- Added FAQ entries for common setup issues (Metro bundler `SyntaxError`, `JWTExpired` on init)
+- Corrected the JWT section to reference official Halo documentation
+- Fixed Full Example to use `requestHaloPermissions()` from `src/permissions.ts`
+
+---
+
+## [1.0.1] - Initial release
+
+- Initial React Native plugin wrapping the Halo Dot Android SDK
+- Supports `initialize`, `startTransaction`, `cardRefundTransaction`, and `cancelTransaction`
+- Event-driven callbacks via `NativeEventEmitter`: initialization, transaction result, UI messages, JWT requests, attestation errors, security errors, and camera events
+- Scheme animations (Visa / Mastercard / Amex) on approved transactions via `AnimationActivity`

package/README.md

@@ -1,163 +1,712 @@
 # halo-sdk-react-native
 
-React Native plugin for the Halo SDK, enabling Android NFC card-present payment transactions.
+A React Native implementation of the [Halo Dot SDK](https://halo-dot-developer-docs.gitbook.io/halo-dot/sdk/1.-getting-started).
+
+The Halo Dot SDK is an Isolating MPoC SDK payment processing software with Attestation & Monitoring Capabilities. It turns an NFC-capable Android phone into a card-present payment terminal, no extra hardware required.
+
+The diagram below shows the SDK boundary and how it interacts with your app, the cardholder's card, and the Halo payment gateway.
+
+![Halo Dot SDK Architecture](https://static.dev.haloplus.io/static/mpos/readme/assets/full_process_MIPS_1200.png)
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Developer Portal Registration](#developer-portal-registration)
+- [Getting Started](#getting-started)
+  - [Create a React Native App](#create-a-react-native-app)
+  - [Environment Setup](#environment-setup)
+  - [Plugin Installation](#plugin-installation)
+  - [Native Module Setup](#native-module-setup)
+  - [AndroidManifest Permissions](#androidmanifest-permissions)
+  - [JWT — What It Is and How to Set It Up](#jwt--what-it-is-and-how-to-set-it-up)
+- [Usage](#usage)
+  - [Step 1 — Request Permissions](#step-1--request-permissions)
+  - [Step 2 — Set Up Callbacks](#step-2--set-up-callbacks)
+  - [Step 3 — Initialize the SDK](#step-3--initialize-the-sdk)
+  - [Step 4 — Run a Transaction](#step-4--run-a-transaction)
+  - [Full Example](#full-example)
+- [API Reference](#api-reference)
+  - [Result Types](#result-types)
+- [Documentation](#documentation)
+- [Testing](#testing)
+- [FAQ](#faq)
+
+---
 
 ## Requirements
 
-- React Native 0.73+
-- Android SDK 29+ (minSdkVersion 29)
-- NFC-capable Android device
+| Requirement | Minimum |
+|---|---|
+| [React Native](https://reactnative.dev/) | 0.73+ |
+| [Java](https://www.java.com/en/) | 21 |
+| Android `minSdkVersion` | 29 |
+| Android `compileSdkVersion` / `targetSdkVersion` | 34+ |
+| Device | NFC-capable Android phone |
+| IDE | [Android Studio](https://developer.android.com/studio/install) recommended |
 
-## Installation
+You will also need:
+- A developer account on the [Halo developer portal](https://go.developerportal.qa.haloplus.io/)
+- A signed Non-Disclosure Agreement (NDA), available on the portal
+- A JWT — generated via the developer portal or your own backend (see [JWT section](#jwt--what-it-is-and-how-to-set-it-up))
 
-### 1. Install the package
+> **Note:** Android is the only supported platform for now.
 
-Add the package to your project using npm or yarn:
+---
+
+## Developer Portal Registration
+
+You must register on the QA (UAT) environment before going to production.
+
+1. Go to [go.developerportal.qa.haloplus.io](https://go.developerportal.qa.haloplus.io/) and create an account
+2. Verify your account via OTP
+3. Click **Access the SDK**
+   ![access sdk](https://static.dev.haloplus.io/static/mpos/readme/assets/access_sdk.jpg)
+4. Download and accept the NDA
+5. Submit your RSA **public key** and create an **Issuer name** — these are used to verify the JWTs your app will sign
+   ![public key](https://static.dev.haloplus.io/static/mpos/readme/assets/public_key.png)
+6. Copy your **Access Key** and **Secret Key** — you will need these to download the SDK from the Halo Maven repo
+   ![access key](https://static.dev.haloplus.io/static/mpos/readme/assets/access_key.png)
+
+---
+
+## Getting Started
+
+### Create a React Native App
+
+If you don't already have a React Native project, create one:
 
 ```bash
-npm install halo-sdk-react-native
+npx react-native init MyHaloApp
+cd MyHaloApp
+```
+
+### Environment Setup
+
+1. Make sure you have **Java 21** installed. Run `java -version` to check.
+
+2. Open `android/app/build.gradle` and confirm `minSdkVersion` is `29` or higher:
+
+```gradle
+android {
+    defaultConfig {
+        applicationId "com.yourcompany.myapp"
+        minSdkVersion 29       // <-- must be 29+
+        targetSdkVersion 34
+        compileSdkVersion 34
+        // ...
+    }
+}
 ```
 
+3. See the [FAQ](#faq) if you have trouble with these SDK version settings.
+
+### Plugin Installation
+
+**1.** Install the npm package:
+
 ```bash
+npm install halo-sdk-react-native
+# or
 yarn add halo-sdk-react-native
 ```
 
-### 2. Configure AWS credentials for the Halo Maven repository
-
-The plugin fetches the Halo SDK from an S3-backed Maven repo. Provide credentials in `android/local.properties`:
+**2.** The plugin downloads the Halo SDK binaries from an S3-backed Maven repo. Add your credentials (from the [developer portal](#developer-portal-registration)) to `android/local.properties` (create the file if it doesn't exist):
 
 ```properties
 aws.accesskey=YOUR_ACCESS_KEY
 aws.secretkey=YOUR_SECRET_KEY
-aws.token=YOUR_SESSION_TOKEN   # optional
 ```
 
-Or set environment variables `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN`.
-
-### 3. Register the native module
+> **Important:** Never commit `local.properties` to source control. Add it to your `.gitignore`
 
-In your `MainApplication`, add `HaloSdkPackage` to `getPackages()`:
+**3.** Add the following snippet to `android/app/build.gradle` so Gradle can read `local.properties` (it may already be there in newer RN templates):
 
-```kotlin
-override fun getPackages(): List<ReactPackage> = listOf(
-    MainReactPackage(),
-    HaloSdkPackage(),
-)
+```gradle
+def localProperties = new Properties()
+def localPropertiesFile = rootProject.file('local.properties')
+if (localPropertiesFile.exists()) {
+    localPropertiesFile.withReader('UTF-8') { reader ->
+        localProperties.load(reader)
+    }
+}
 ```
 
-### 4. Extend HaloReactActivity
+### Native Module Setup
 
-In `MainActivity`, extend `HaloReactActivity` instead of `ReactActivity`:
+**4.** Open `android/app/src/main/kotlin/.../MainActivity.kt` and extend `HaloReactActivity` instead of `ReactActivity`:
 
 ```kotlin
+import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.fabricEnabled
+import com.facebook.react.defaults.DefaultReactActivityDelegate
 import za.co.synthesis.halo.sdkreactnativeplugin.HaloReactActivity
 
 class MainActivity : HaloReactActivity() {
-    override fun getMainComponentName(): String = "YourAppName"
+
+    override fun getMainComponentName(): String = "MyHaloApp"
+
     override fun createReactActivityDelegate() =
         DefaultReactActivityDelegate(this, mainComponentName, fabricEnabled)
 }
 ```
 
-This ensures Halo SDK lifecycle management works correctly.
+This replaces `ReactActivity` so that NFC foreground dispatch and the Halo SDK lifecycle are managed automatically.
+
+**5.** Open `android/app/src/main/kotlin/.../MainApplication.kt` and register `HaloSdkPackage`:
+
+```kotlin
+import android.app.Application
+import com.facebook.react.PackageList
+import com.facebook.react.ReactApplication
+import com.facebook.react.ReactNativeHost
+import com.facebook.react.ReactPackage
+import com.facebook.react.defaults.DefaultReactNativeHost
+import com.facebook.soloader.SoLoader
+import za.co.synthesis.halo.sdkreactnativeplugin.HaloSdkPackage  // <-- add this import
+
+class MainApplication : Application(), ReactApplication {
+
+    override val reactNativeHost: ReactNativeHost =
+        object : DefaultReactNativeHost(this) {
+            override fun getPackages(): List<ReactPackage> =
+                PackageList(this).packages.apply {
+                    add(HaloSdkPackage())  // <-- add this line
+                }
+
+            override fun getJSMainModuleName(): String = "index"
+            override fun getUseDeveloperSupport(): Boolean = BuildConfig.DEBUG
+            override val isNewArchEnabled: Boolean = false
+            override val isHermesEnabled: Boolean = true
+        }
+
+    override fun onCreate() {
+        super.onCreate()
+        SoLoader.init(this, false)
+    }
+}
+```
+
+### AndroidManifest Permissions
+
+**6.** Add the required permissions to `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+    <uses-feature
+        android:name="android.hardware.camera"
+        android:required="false" />
+
+    <!-- Bluetooth — legacy permissions for API 29/30 -->
+    <uses-permission android:name="android.permission.BLUETOOTH" />
+    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
+
+    <!-- Bluetooth — API 31+ -->
+    <uses-permission android:name="android.permission.BLUETOOTH_SCAN"
+        android:usesPermissionFlags="neverForLocation" />
+    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+
+    <!-- Location (required for Bluetooth LE scanning) -->
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
+
+    <!-- Other -->
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.CAMERA" />
+    <uses-permission android:name="android.permission.NFC" />
+
+    <uses-feature android:name="android.hardware.nfc" android:required="true" />
+
+    <application ...>
+        <activity
+            android:name=".MainActivity"
+            ...>
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+
+            <!-- Required: NFC foreground dispatch -->
+            <intent-filter>
+                <action android:name="android.nfc.action.TECH_DISCOVERED" />
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>
+```
+
+---
+
+## JWT — What It Is and How to Set It Up
+
+Every call to the Halo SDK must include a valid JWT. The SDK requests one via the `onRequestJWT` callback whenever it needs to authenticate.
+
+A JWT must be obtained from your backend or generated using your RSA private key and the credentials from the [developer portal](https://go.developerportal.qa.haloplus.io/). See the [Halo developer documentation](https://halo-dot-developer-docs.gitbook.io/halo-dot/sdk) for the required claims. For testing, paste a valid token directly into `Config.tempJwt` as shown below.
+
+Split your config and JWT supply into two files:
+
+**`src/config.ts`** — stores your app settings (never commit real values to source control):
+
+```typescript
+export const Config = {
+  // Paste a valid JWT here for testing.
+  // Regenerate it if the SDK reports JWTExpired on startup.
+  tempJwt: 'eyJ...',
+
+  // Obtained from the developer portal
+  applicationPackageName: 'com.yourcompany.myapp',
+  applicationVersion: '1.0.0',
+  onStartTransactionTimeOut: 300000,  // ms before "tap card" times out
+  enableSchemeAnimations: true,       // show Visa/Mastercard animations
+} as const;
+```
+
+**`src/jwt/JwtToken.ts`**: supplies the JWT when the SDK asks for one:
+
+```typescript
+import { Config } from '../config';
+
+export function getJwt(): string {
+  if (Config.tempJwt) {
+    return Config.tempJwt;
+  }
+  throw new Error('No JWT configured. Set Config.tempJwt in src/config.ts.');
+}
+```
+
+> **Important:** Add `config.ts` to `.gitignore` so you never accidentally commit a real token to source control.
+
+---
 
 ## Usage
 
+### Step 1 — Request Permissions
+
+Request the Android runtime permissions before initialising the SDK. Android 12+ (API 31+) uses new Bluetooth permission names.
+
 ```typescript
+// src/permissions.ts
+import { PermissionsAndroid, Platform } from 'react-native';
+
+export async function requestHaloPermissions(): Promise<void> {
+  if (Platform.OS !== 'android') return;
+
+  const sdkVersion =
+    typeof Platform.Version === 'number'
+      ? Platform.Version
+      : parseInt(Platform.Version, 10);
+
+  const permissions: string[] = [
+    PermissionsAndroid.PERMISSIONS.CAMERA,
+    PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION,
+  ];
+
+  if (sdkVersion >= 31) {
+    // Android 12+ Bluetooth permissions
+    permissions.push(
+      PermissionsAndroid.PERMISSIONS.BLUETOOTH_SCAN,
+      PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT,
+    );
+  }
+
+  await PermissionsAndroid.requestMultiple(permissions);
+}
+```
+
+### Step 2 — Set Up Callbacks
+
+The SDK communicates back to your app through an `IHaloCallbacks` object you provide. Each callback corresponds to a different type of event.
+
+```typescript
+// src/haloCallbacks.ts
 import {
-  HaloSdk,
   type IHaloCallbacks,
+  type HaloAttestationHealthResult,
   type HaloInitializationResult,
   type HaloTransactionResult,
   type HaloUIMessage,
-  type HaloAttestationHealthResult,
 } from 'halo-sdk-react-native';
+import { getJwt } from './jwt/JwtToken';
+
+export function buildCallbacks(options: {
+  onStatusChange: (msg: string) => void;
+  onError: (msg: string) => void;
+  onTransactionResult: (result: HaloTransactionResult) => void;
+}): IHaloCallbacks {
+  return {
+    // Called when the SDK finishes starting up.
+    // Check resultType === 'Initialized' for successful init.
+    onInitializationResult(result: HaloInitializationResult) {
+      if (result.resultType === 'Initialized') {
+        options.onStatusChange('SDK ready — present a card to pay');
+      } else {
+        options.onError(`Initialisation failed: ${result.resultType} (${result.errorCode})`);
+      }
+    },
+
+    // Called when a card tap completes (approved, declined, or error)
+    onHaloTransactionResult(result: HaloTransactionResult) {
+      options.onTransactionResult(result);
+    },
+
+    // Called repeatedly during a transaction to tell you what to show the user
+    // e.g. "PRESENT_CARD", "PROCESSING", "APPROVED"
+    onHaloUIMessage(message: HaloUIMessage) {
+      options.onStatusChange(message.msgID);
+    },
+
+    // The SDK asks you for a fresh JWT whenever it needs one
+    onRequestJWT(jwtCallback: (jwt: string) => void) {
+      try {
+        jwtCallback(getJwt());
+      } catch (err: any) {
+        options.onError(`JWT error: ${err.message}`);
+      }
+    },
+
+    // Device failed attestation (tampered OS, emulator, etc.)
+    onAttestationError(details: HaloAttestationHealthResult) {
+      options.onError(`Attestation error: ${details.errorCode}`);
+    },
+
+    // A security check failed (e.g. invalid JWT, revoked merchant)
+    onSecurityError(errorCode: string) {
+      options.onError(`Security error: ${errorCode}`);
+    },
+
+    // The SDK released the camera (e.g. card scheme animation finished)
+    onCameraControlLost() {
+      console.log('Camera released by SDK');
+    },
+  };
+}
+```
+
+### Step 3 — Initialize the SDK
+
+Call `HaloSdk.initialize` once, before running any transactions. A good place is in a `useEffect` when your payment screen mounts.
+
+```typescript
+import { HaloSdk } from 'halo-sdk-react-native';
+import { Config } from './config';
+import { requestHaloPermissions } from './permissions';
+import { buildCallbacks } from './haloCallbacks';
+
+async function setupSdk(
+  onStatusChange: (msg: string) => void,
+  onError: (msg: string) => void,
+  onTransactionResult: (result: any) => void,
+): Promise<void> {
+  // 1. Request permissions first
+  await requestHaloPermissions();
+
+  // 2. Build your callbacks
+  const callbacks = buildCallbacks({ onStatusChange, onError, onTransactionResult });
+
+  // 3. Initialise — the SDK will call onInitializationResult when ready
+  await HaloSdk.initialize(
+    callbacks,
+    Config.applicationPackageName,  // e.g. 'com.yourcompany.myapp'
+    Config.applicationVersion,      // e.g. '1.0.0'
+    Config.onStartTransactionTimeOut, // ms before a tap times out (default 300000)
+    Config.enableSchemeAnimations,    // show Visa/Mastercard animations
+  );
+}
+```
+
+### Step 4 — Run a Transaction
 
-const callbacks: IHaloCallbacks = {
-  onInitializationResult(result: HaloInitializationResult) {
-    console.log('Initialized:', result.resultType);
-  },
-  onHaloTransactionResult(result: HaloTransactionResult) {
-    console.log('Transaction:', result.resultType, result.errorCode);
-  },
-  onHaloUIMessage(message: HaloUIMessage) {
-    console.log('UI Message:', message.msgID);
-  },
-  onAttestationError(details: HaloAttestationHealthResult) {
-    console.error('Attestation error:', details.errorCode);
-  },
-  onRequestJWT(jwtCallback: (jwt: string) => void) {
-    const jwt = getJwtFromYourServer();
-    jwtCallback(jwt);
-  },
-  onSecurityError(errorCode: string) {
-    console.error('Security error:', errorCode);
-  },
-  onCameraControlLost() {
-    console.warn('Camera control lost');
-  },
-};
-
-// Initialize once (e.g. on app start)
-await HaloSdk.initialize(
-  callbacks,
-  'com.your.package.name',
-  '1.0.0',
-  300000, // transaction timeout in ms (optional, default 300000)
-  true,   // enable scheme animations (optional)
-);
-
-// Start a purchase
-const result = await HaloSdk.startTransaction(10.50, 'REF-001', 'ZAR');
-
-// Start a card refund
-const refund = await HaloSdk.cardRefundTransaction(10.50, 'REF-001', 'ZAR');
-
-// Cancel current transaction
+Once the SDK is initialised, you can charge a card:
+
+```typescript
+// Charge R 10.50
+const result = await HaloSdk.startTransaction(10.50, 'ORDER-001', 'ZAR');
+console.log(result.resultType); // e.g. "tap_started"
+
+// Refund R 10.50 to the original card
+const refund = await HaloSdk.cardRefundTransaction(10.50, 'ORDER-001', 'ZAR');
+
+// Cancel a transaction that is waiting for a tap
 await HaloSdk.cancelTransaction();
 ```
 
-## API
+`startTransaction` and `cardRefundTransaction` resolve immediately once the tap is registered, the final payment outcome arrives through `onHaloTransactionResult`.
+
+### Full Example
+
+Below is a minimal but complete payment screen taken directly from the example app in this repo:
+
+```tsx
+// App.tsx
+import React, { useEffect, useState } from 'react';
+import {
+  ActivityIndicator,
+  Text,
+  TextInput,
+  TouchableOpacity,
+  View,
+} from 'react-native';
+import {
+  HaloSdk,
+  type HaloTransactionResult,
+  type IHaloCallbacks,
+} from 'halo-sdk-react-native';
+import { getJwt } from './src/jwt/JwtToken';
+import { Config } from './src/config';
+import { requestHaloPermissions } from './src/permissions';
+
+export default function App() {
+  const [amount, setAmount] = useState('');
+  const [merchantRef, setMerchantRef] = useState('');
+  const [status, setStatus] = useState('Initialising...');
+  const [isReady, setIsReady] = useState(false);
+
+  useEffect(() => {
+    initSdk();
+  }, []);
+
+  async function initSdk() {
+    await requestHaloPermissions();
+
+    const callbacks: IHaloCallbacks = {
+      onInitializationResult(result) {
+        setIsReady(result.resultType === 'Initialized');
+        setStatus(
+          result.resultType === 'Initialized'
+            ? 'Ready — enter amount and tap Charge'
+            : `Init failed: ${result.resultType} (${result.errorCode})`,
+        );
+      },
+      onHaloTransactionResult(result: HaloTransactionResult) {
+        setStatus(`Result: ${result.resultType} ${result.errorCode}`);
+      },
+      onHaloUIMessage(message) {
+        // The SDK sends messages like "PRESENT_CARD", "PROCESSING", "APPROVED"
+        setStatus(message.msgID);
+      },
+      onRequestJWT(jwtCallback) {
+        try {
+          jwtCallback(getJwt());
+        } catch (e: any) {
+          setStatus(`JWT error: ${e.message}`);
+        }
+      },
+      onAttestationError(details) {
+        setStatus(`Attestation error: ${details.errorCode}`);
+      },
+      onSecurityError(errorCode) {
+        setStatus(`Security error: ${errorCode}`);
+      },
+      onCameraControlLost() {},
+    };
+
+    HaloSdk.initialize(
+      callbacks,
+      Config.applicationPackageName,
+      Config.applicationVersion,
+      Config.onStartTransactionTimeOut,
+      Config.enableSchemeAnimations,
+    ).catch(e => setStatus(`SDK error: ${e.message}`));
+  }
+
+  async function charge() {
+    if (!amount || !merchantRef) {
+      setStatus('Please enter amount and merchant reference');
+      return;
+    }
+    try {
+      const result = await HaloSdk.startTransaction(parseFloat(amount), merchantRef, 'ZAR');
+      setStatus(`Tap accepted: ${result.resultType}`);
+    } catch (e: any) {
+      setStatus(`Error: ${e.message}`);
+    }
+  }
+
+  return (
+    <View style={{ flex: 1, padding: 24, justifyContent: 'center' }}>
+      <Text style={{ fontSize: 13, color: '#555', marginBottom: 16 }}>{status}</Text>
+
+      {!isReady ? (
+        <ActivityIndicator size="large" />
+      ) : (
+        <>
+          <TextInput
+            placeholder="Amount (e.g. 10.50)"
+            value={amount}
+            onChangeText={setAmount}
+            keyboardType="decimal-pad"
+            style={{ borderWidth: 1, borderColor: '#ccc', padding: 8, marginBottom: 8, borderRadius: 4 }}
+          />
+          <TextInput
+            placeholder="Merchant reference (e.g. ORDER-001)"
+            value={merchantRef}
+            onChangeText={setMerchantRef}
+            style={{ borderWidth: 1, borderColor: '#ccc', padding: 8, marginBottom: 16, borderRadius: 4 }}
+          />
+          <TouchableOpacity
+            onPress={charge}
+            style={{ backgroundColor: '#1976D2', padding: 14, borderRadius: 8, alignItems: 'center' }}>
+            <Text style={{ color: '#fff', fontSize: 16, fontWeight: '600' }}>Charge</Text>
+          </TouchableOpacity>
+        </>
+      )}
+    </View>
+  );
+}
+```
+
+---
+
+## API Reference
 
 ### `HaloSdk.initialize(callbacks, packageName, version, timeout?, animations?)`
 
 Initialises the SDK. Must be called before any transaction methods.
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `callbacks` | `IHaloCallbacks` | Event handler object |
-| `applicationPackageName` | `string` | Your app's package name |
-| `applicationVersion` | `string` | Your app's version string |
-| `onStartTransactionTimeOut` | `number?` | Tap timeout in ms (default 300000) |
-| `enableSchemeAnimations` | `boolean?` | Show Visa/Mastercard/Amex animations on approval |
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `callbacks` | `IHaloCallbacks` | — | Your callback handler object |
+| `applicationPackageName` | `string` | — | Your app's Android package name |
+| `applicationVersion` | `string` | — | Your app's version string |
+| `onStartTransactionTimeOut` | `number?` | `300000` | Time in ms to wait for a card tap |
+| `enableSchemeAnimations` | `boolean?` | `false` | Show Visa/Mastercard/Amex animations on approval |
 
 ### `HaloSdk.startTransaction(amount, reference, currency)`
 
-Starts a purchase transaction. Resolves with a `HaloStartTransactionResult` once the card tap is accepted or rejected.
+Starts a purchase transaction. Prompts the user to tap their card.
+
+| Parameter | Type | Example |
+|---|---|---|
+| `transactionAmount` | `number` | `10.50` |
+| `merchantTransactionReference` | `string` | `'ORDER-001'` |
+| `transactionCurrency` | `string` | `'ZAR'` |
+
+Returns `Promise<HaloStartTransactionResult>` — resolves when the card tap is registered. The final outcome arrives via `onHaloTransactionResult`.
 
 ### `HaloSdk.cardRefundTransaction(amount, reference, currency)`
 
-Starts a card-present refund transaction.
+Starts a card-present refund. Same parameters as `startTransaction`.
 
 ### `HaloSdk.cancelTransaction()`
 
-Requests cancellation of the current in-progress transaction.
+Cancels the current in-progress transaction (e.g. if the user presses Cancel while waiting for a tap).
 
-## Callbacks (`IHaloCallbacks`)
+### Callbacks (`IHaloCallbacks`)
 
-| Callback                   | Description                                                           |
-|----------------------------|-----------------------------------------------------------------------|
-| `onInitializationResult`   | SDK initialisation complete or failed                                 |
-| `onHaloTransactionResult`  | Final transaction outcome                                             |
-| `onHaloUIMessage`          | Prompt to display to the cardholder (e.g. "Present card")             |
-| `onRequestJWT`             | SDK needs a fresh JWT; call the provided `jwtCallback` with the token |
-| `onAttestationError`       | Device attestation failed                                             |
-| `onSecurityError`          | Security check failed                                                 |
-| `onCameraControlLost`      | SDK released camera control                                           |
+| Callback | When it fires |
+|---|---|
+| `onInitializationResult(result)` | SDK startup complete (success or failure) |
+| `onHaloTransactionResult(result)` | Final payment outcome; approved, declined, or error |
+| `onHaloUIMessage(message)` | Prompt to show the user during a tap: `PRESENT_CARD`, `PROCESSING`, `APPROVED`, etc. |
+| `onRequestJWT(jwtCallback)` | SDK needs a fresh JWT; call `jwtCallback(yourJwtString)` |
+| `onAttestationError(details)` | Device integrity check failed (rooted device, emulator, etc.) |
+| `onSecurityError(errorCode)` | JWT invalid, merchant revoked, or other security failure |
+| `onCameraControlLost()` | SDK has finished using the camera |
 
-## Building the plugin
+### Result Types
 
-```bash
-npm install
-npm run build
+`resultType` and `errorCode` are plain strings serialised from native Android enums. Use these known values in your conditional logic.
+
+**`HaloInitializationResult.resultType`**
+
+| Value | Meaning |
+|---|---|
+| `'Initialized'` | SDK ready; safe to call `startTransaction` |
+| `'RemoteAttestationFailure'` | Cloud attestation failed; inspect `errorCode` for the reason |
+| `'LocalAttestationFailure'` | Device integrity check failed (rooted device, emulator, etc.) |
+
+**`HaloInitializationResult.errorCode`** (when `resultType !== 'Initialized'`)
+
+| Value | Meaning |
+|---|---|
+| `'OK'` | No error — accompanies `resultType: 'Initialized'` |
+| `'JWTExpired'` | The JWT has expired — generate a fresh one |
+
+
+**`HaloTransactionResult.resultType`**
+
+| Value | Meaning |
+|---|---|
+| `'Approved'` | Transaction approved by the payment network |
+| `'Declined'` | Card declined |
+| `'Cancelled'` | Transaction cancelled (e.g. via `cancelTransaction()`) |
+| `'Error'` | An error occurred — inspect `errorCode` and `errorDetails` |
+
+---
+
+## Documentation
+
+Full SDK documentation: [halo-dot-developer-docs.gitbook.io](https://halo-dot-developer-docs.gitbook.io/halo-dot/sdk)
+
+---
+
+## Testing
+
+All transactions are void until your NDA is fully executed.
+
+You can simulate card taps using a virtual NFC card app such as [Visa Mobile CDET](https://apkpure.com/visa-mobile-cdet/com.visa.app.cdet) on a second Android device.
+
+---
+
+## FAQ
+
+**Q: How do I set `compileSdkVersion` / `minSdkVersion` if they're not set or causing issues?**
+
+You can define them in `android/local.properties` and read them in Gradle:
+
+```properties
+sdk.dir=C\:\\Users\\yourname\\Library\\Android/Sdk
+aws.accesskey=YOUR_ACCESS_KEY
+aws.secretkey=YOUR_SECRET_KEY
+compileSdkVersion=34
+minSdkVersion=29
+```
+
+```gradle
+// android/app/build.gradle
+compileSdkVersion localProperties.getProperty('compileSdkVersion').toInteger()
 ```
+
+---
+
+**Q: The SDK fails to download / Gradle sync fails.**
+
+- Confirm `aws.accesskey` and `aws.secretkey` are in `android/local.properties` with the exact casing shown
+- Open the `android` folder in Android Studio and run **File → Sync Project with Gradle Files**
+- Make sure you accepted the NDA on the developer portal (access is blocked until the NDA is signed)
+
+---
+
+**Q: I get a build error about `HaloReactActivity` or `HaloSdkPackage` not found.**
+
+- Confirm the npm package is installed: `npm install halo-sdk-react-native`
+- Confirm `HaloSdkPackage()` is added in `MainApplication.kt`
+- Confirm `MainActivity` extends `HaloReactActivity` (not `ReactActivity`)
+- Run a Gradle sync in Android Studio
+
+---
+
+**Q: The SDK initialises but transactions never complete.**
+
+- Check that all [AndroidManifest permissions](#androidmanifest-permissions) are declared, especially the NFC `intent-filter` block
+- Check that the NFC intent-filter is inside the `<activity>` block for `MainActivity`
+- Verify your JWT is valid using `POST https://kernelserver.qa.haloplus.io/<sdk-version>/tokens/checkjwt`
+- Check that `minSdkVersion` ≥ 29 and `compileSdkVersion` / `targetSdkVersion` ≥ 34
+
+---
+
+**Q: How do I get a JWT for testing?**
+
+A JWT must be generated using your RSA private key and the credentials from the [developer portal](https://go.developerportal.qa.haloplus.io/). See the [Halo developer documentation](https://halo-dot-developer-docs.gitbook.io/halo-dot/sdk) for the required claims and signing algorithm. Once you have a valid token, paste it into `Config.tempJwt` in your `config.ts`.
+
+---
+
+**Q: `onInitializationResult` fires with `resultType: 'RemoteAttestationFailure'` and `errorCode: 'JWTExpired'`.**
+
+Your temp JWT has expired. Developer-portal tokens are short-lived (typically 15 minutes). This is expected behaviour — the SDK fires a failure callback with the cached/expired token, then automatically requests a new JWT via `onRequestJWT` and retries. If `onInitializationResult` fires a **second time** shortly after with `resultType: 'Initialized'`, everything is working correctly.
+
+If the second successful callback never arrives:
+1. Generate a fresh token and update `Config.tempJwt`
+2. Make sure your `onRequestJWT` callback calls `jwtCallback(yourJwt)` synchronously — async calls are not supported without extra handling

package/android/build.gradle

@@ -21,7 +21,7 @@ rootProject.allprojects {
         ]
 
         flatDir {
-            dirs project(':halo_sdk_react_native_plugin').file('libs')
+            dirs "${project(':halo-sdk-react-native').projectDir}/libs"
         }
 
         repos.each { repo ->
@@ -81,8 +81,8 @@ dependencies {
     implementation 'androidx.appcompat:appcompat:1.6.1'
 
     // Halo SDK
-    releaseImplementation group: "za.co.synthesis.halo", name: "sdk", version: "$sdkVersion", changing: true
-    debugImplementation group: "za.co.synthesis.halo", name: "sdk", version: "$sdkVersion-debug", changing: true
+    releaseApi group: "za.co.synthesis.halo", name: "sdk", version: "$sdkVersion", changing: true
+    debugApi group: "za.co.synthesis.halo", name: "sdk", version: "$sdkVersion-debug", changing: true
 
     implementation(name: 'VisaSensoryBranding', ext: 'aar')
     implementation(name: 'sonic-sdk-release-1.5.0', ext: 'aar')

package/android/src/main/kotlin/za/co/synthesis/halo/sdkreactnativeplugin/HaloSdkModule.kt

@@ -24,17 +24,20 @@ class HaloSdkModule(reactContext: ReactApplicationContext) :
 
     @ReactMethod
     fun initializeHaloSDK(args: ReadableMap, promise: Promise) {
-        haloSdkImplementation.initializeHaloSDK(promise, args.toHashMap())
+        @Suppress("UNCHECKED_CAST")
+        haloSdkImplementation.initializeHaloSDK(promise, args.toHashMap() as HashMap<String, Any>)
     }
 
     @ReactMethod
     fun startTransaction(args: ReadableMap, promise: Promise) {
-        haloSdkImplementation.startTransaction(promise, args.toHashMap())
+        @Suppress("UNCHECKED_CAST")
+        haloSdkImplementation.startTransaction(promise, args.toHashMap() as HashMap<String, Any>)
     }
 
     @ReactMethod
     fun cardRefundTransaction(args: ReadableMap, promise: Promise) {
-        haloSdkImplementation.startTransaction(promise, args.toHashMap(), TransactionType.Refund)
+        @Suppress("UNCHECKED_CAST")
+        haloSdkImplementation.startTransaction(promise, args.toHashMap() as HashMap<String, Any>, TransactionType.Refund)
     }
 
     @ReactMethod
@@ -57,7 +60,7 @@ class HaloSdkModule(reactContext: ReactApplicationContext) :
     // Keep UIContext activity reference up to date
     override fun onHostResume() {
         Log.d(TAG, "onHostResume")
-        UIContext.updateActivity(currentActivity)
+        UIContext.updateActivity(reactApplicationContext.currentActivity)
     }
 
     override fun onHostPause() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "halo-sdk-react-native",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "React Native plugin for Halo SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,7 +10,8 @@
     "android/libs",
     "android/build.gradle",
     "android/settings.gradle",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc"