halo-sdk-react-native 1.0.1 → 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

@@ -19,8 +19,6 @@ The diagram below shows the SDK boundary and how it interacts with your app, the
   - [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)
-    - [JWT Lifetime](#jwt-lifetime)
-    - [JWT Claims](#jwt-claims)
 - [Usage](#usage)
   - [Step 1 — Request Permissions](#step-1--request-permissions)
   - [Step 2 — Set Up Callbacks](#step-2--set-up-callbacks)
@@ -28,6 +26,7 @@ The diagram below shows the SDK boundary and how it interacts with your app, the
   - [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)
@@ -50,10 +49,7 @@ You will also need:
 - 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))
 
-Recommended libraries:
-- [`react-native-permissions`](https://www.npmjs.com/package/react-native-permissions) `^4.0.0` — runtime permission handling
-
-> **Note:** Android is the only supported platform.
+> **Note:** Android is the only supported platform for now.
 
 ---
 
@@ -80,7 +76,7 @@ You must register on the QA (UAT) environment before going to production.
 If you don't already have a React Native project, create one:
 
 ```bash
-npx react-native init MyHaloApp --version 0.73.0
+npx react-native init MyHaloApp
 cd MyHaloApp
 ```
 
@@ -114,13 +110,7 @@ npm install halo-sdk-react-native
 yarn add halo-sdk-react-native
 ```
 
-**2.** Install `react-native-permissions` (recommended for runtime permission handling):
-
-```bash
-npm install react-native-permissions
-```
-
-**3.** 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):
+**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
@@ -129,7 +119,7 @@ aws.secretkey=YOUR_SECRET_KEY
 
 > **Important:** Never commit `local.properties` to source control. Add it to your `.gitignore`
 
-**4.** Add the following snippet to `android/app/build.gradle` so Gradle can read `local.properties` (it may already be there in newer RN templates):
+**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):
 
 ```gradle
 def localProperties = new Properties()
@@ -143,7 +133,7 @@ if (localPropertiesFile.exists()) {
 
 ### Native Module Setup
 
-**5.** Open `android/app/src/main/kotlin/.../MainActivity.kt` and 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
@@ -161,7 +151,7 @@ class MainActivity : HaloReactActivity() {
 
 This replaces `ReactActivity` so that NFC foreground dispatch and the Halo SDK lifecycle are managed automatically.
 
-**6.** Open `android/app/src/main/kotlin/.../MainApplication.kt` and register `HaloSdkPackage`:
+**5.** Open `android/app/src/main/kotlin/.../MainApplication.kt` and register `HaloSdkPackage`:
 
 ```kotlin
 import android.app.Application
@@ -197,7 +187,7 @@ class MainApplication : Application(), ReactApplication {
 
 ### AndroidManifest Permissions
 
-**7.** Add the required permissions to `android/app/src/main/AndroidManifest.xml`:
+**6.** Add the required permissions to `android/app/src/main/AndroidManifest.xml`:
 
 ```xml
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
@@ -251,25 +241,21 @@ class MainApplication : Application(), ReactApplication {
 
 ## JWT — What It Is and How to Set It Up
 
-Every call to the Halo SDK must include a valid JWT. Think of it as a short-lived, signed pass that proves your app is authorised to accept payments for a given merchant.
-
-The JWT is issued either by the [developer portal](https://go.developerportal.qa.haloplus.io/) (for testing) or by your own backend server (for production). The portal verifies it using the RSA **public key** you submitted during registration.
+Every call to the Halo SDK must include a valid JWT. The SDK requests one via the `onRequestJWT` callback whenever it needs to authenticate.
 
-> **For testing:** use the portal's **Generate Token** tool to get a pre-generated JWT. You do not need to implement signing yourself to get started.
+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.
 
-**Recommended approach:** split credentials and JWT retrieval into two files.
+Split your config and JWT supply into two files:
 
-**`src/config.ts`** — stores your app's settings (never commit real values to source control):
+**`src/config.ts`** — stores your app settings (never commit real values to source control):
 
 ```typescript
-// Copy this file to config.ts and fill in your values.
-// config.ts should be added to .gitignore.
 export const Config = {
-  // Paste a JWT generated from the developer portal here for testing.
-  // In production, fetch this from your backend instead.
+  // Paste a valid JWT here for testing.
+  // Regenerate it if the SDK reports JWTExpired on startup.
   tempJwt: 'eyJ...',
 
-  // SDK initialisation options (all obtained from the developer portal)
+  // Obtained from the developer portal
   applicationPackageName: 'com.yourcompany.myapp',
   applicationVersion: '1.0.0',
   onStartTransactionTimeOut: 300000,  // ms before "tap card" times out
@@ -277,46 +263,20 @@ export const Config = {
 } as const;
 ```
 
-**`src/jwt/JwtToken.ts`** — supplies the JWT when the SDK asks for one:
+**`src/jwt/JwtToken.ts`**: supplies the JWT when the SDK asks for one:
 
 ```typescript
 import { Config } from '../config';
 
-/**
- * Returns the JWT for the Halo SDK's onRequestJWT callback.
- *
- * For testing: set Config.tempJwt to a token from the developer portal.
- * For production: replace this with a fetch from your backend server.
- */
 export function getJwt(): string {
   if (Config.tempJwt) {
     return Config.tempJwt;
   }
-  throw new Error(
-    'No JWT configured. Set Config.tempJwt in src/config.ts, ' +
-    'or implement a backend fetch here.',
-  );
+  throw new Error('No JWT configured. Set Config.tempJwt in src/config.ts.');
 }
 ```
 
-> **Note:** `getJwt` is synchronous here for simplicity. If you fetch the JWT from a backend, make it `async` and update the `onRequestJWT` callback accordingly.
-
-### JWT Lifetime
-
-Keep the lifetime short — 15 minutes is the recommended maximum. A stolen JWT can only be abused for as long as it remains valid.
-
-### JWT Claims
-
-| Field | Type | Description |
-|---|---|---|
-| `alg` | String | `RS512` — RSA + SHA-512. Asymmetric signing is required so the server can verify without being able to forge tokens. |
-| `iss` | String | Your issuer name, registered on the developer portal (e.g. `authserver.haloplus.io`). |
-| `sub` | String | Your merchant or application ID. |
-| `aud` | String | The Halo kernel server URL (e.g. `kernelserver.qa.haloplus.io`). |
-| `usr` | String | The signed-in operator/user identifier. |
-| `iat` | NumericDate | UTC timestamp of when the token was created. |
-| `exp` | NumericDate | UTC expiry timestamp. |
-| `aud_fingerprints` | String | CSV of SHA-256 TLS fingerprints for the kernel server. Supports multiple values for certificate rotation. |
+> **Important:** Add `config.ts` to `.gitignore` so you never accidentally commit a real token to source control.
 
 ---
 
@@ -376,12 +336,13 @@ export function buildCallbacks(options: {
   onTransactionResult: (result: HaloTransactionResult) => void;
 }): IHaloCallbacks {
   return {
-    // Called when the SDK finishes starting up
+    // Called when the SDK finishes starting up.
+    // Check resultType === 'Initialized' for successful init.
     onInitializationResult(result: HaloInitializationResult) {
-      if (result.resultType === 'success') {
+      if (result.resultType === 'Initialized') {
         options.onStatusChange('SDK ready — present a card to pay');
       } else {
-        options.onError(`Initialisation failed: ${result.errorCode}`);
+        options.onError(`Initialisation failed: ${result.resultType} (${result.errorCode})`);
       }
     },
 
@@ -471,7 +432,7 @@ const refund = await HaloSdk.cardRefundTransaction(10.50, 'ORDER-001', 'ZAR');
 await HaloSdk.cancelTransaction();
 ```
 
-`startTransaction` and `cardRefundTransaction` resolve immediately once the tap is registered — the final payment outcome arrives through `onHaloTransactionResult`.
+`startTransaction` and `cardRefundTransaction` resolve immediately once the tap is registered, the final payment outcome arrives through `onHaloTransactionResult`.
 
 ### Full Example
 
@@ -482,8 +443,6 @@ Below is a minimal but complete payment screen taken directly from the example a
 import React, { useEffect, useState } from 'react';
 import {
   ActivityIndicator,
-  PermissionsAndroid,
-  Platform,
   Text,
   TextInput,
   TouchableOpacity,
@@ -496,6 +455,7 @@ import {
 } 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('');
@@ -508,33 +468,15 @@ export default function App() {
   }, []);
 
   async function initSdk() {
-    // Request permissions
-    if (Platform.OS === 'android') {
-      const sdkVersion =
-        typeof Platform.Version === 'number'
-          ? Platform.Version
-          : parseInt(Platform.Version, 10);
-
-      const perms: string[] = [
-        PermissionsAndroid.PERMISSIONS.CAMERA,
-        PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION,
-      ];
-      if (sdkVersion >= 31) {
-        perms.push(
-          PermissionsAndroid.PERMISSIONS.BLUETOOTH_SCAN,
-          PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT,
-        );
-      }
-      await PermissionsAndroid.requestMultiple(perms);
-    }
+    await requestHaloPermissions();
 
     const callbacks: IHaloCallbacks = {
       onInitializationResult(result) {
-        setIsReady(result.resultType === 'success');
+        setIsReady(result.resultType === 'Initialized');
         setStatus(
-          result.resultType === 'success'
+          result.resultType === 'Initialized'
             ? 'Ready — enter amount and tap Charge'
-            : `Init failed: ${result.errorCode}`,
+            : `Init failed: ${result.resultType} (${result.errorCode})`,
         );
       },
       onHaloTransactionResult(result: HaloTransactionResult) {
@@ -656,13 +598,42 @@ Cancels the current in-progress transaction (e.g. if the user presses Cancel whi
 | Callback | When it fires |
 |---|---|
 | `onInitializationResult(result)` | SDK startup complete (success or failure) |
-| `onHaloTransactionResult(result)` | Final payment outcome — approved, declined, or error |
+| `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)` |
+| `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 |
 
+### Result Types
+
+`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
@@ -686,7 +657,7 @@ You can simulate card taps using a virtual NFC card app such as [Visa Mobile CDE
 You can define them in `android/local.properties` and read them in Gradle:
 
 ```properties
-sdk.dir=/Users/yourname/Library/Android/sdk
+sdk.dir=C\:\\Users\\yourname\\Library\\Android/Sdk
 aws.accesskey=YOUR_ACCESS_KEY
 aws.secretkey=YOUR_SECRET_KEY
 compileSdkVersion=34
@@ -726,6 +697,16 @@ compileSdkVersion localProperties.getProperty('compileSdkVersion').toInteger()
 
 ---
 
-**Q: How do I get a test JWT quickly without implementing RS512 signing?**
+**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.
 
-Log into the [developer portal](https://go.developerportal.qa.haloplus.io/), navigate to your app, and use the portal's **Generate Token** tool. Paste the result into `Config.tempJwt` in your `config.ts`. Remember to implement proper signing before going to production.
+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

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "halo-sdk-react-native",
-  "version": "1.0.1",
+  "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"