halo-sdk-react-native 1.0.1 → 1.0.3

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()
@@ -141,6 +131,18 @@ if (localPropertiesFile.exists()) {
 }
 ```
 
+**4.** Add the following `packagingOptions` block inside the `android { }` closure in `android/app/build.gradle`. This prevents a duplicate-file error caused by OSGI metadata bundled in the SDK's transitive dependencies:
+
+```gradle
+android {
+    // ... your existing config ...
+
+    packagingOptions {
+        resources.excludes.add("META-INF/versions/9/OSGI-INF/MANIFEST.MF")
+    }
+}
+```
+
 ### Native Module Setup
 
 **5.** Open `android/app/src/main/kotlin/.../MainActivity.kt` and extend `HaloReactActivity` instead of `ReactActivity`:
@@ -161,43 +163,9 @@ 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`:
-
-```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
 
-**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"
@@ -228,7 +196,14 @@ class MainApplication : Application(), ReactApplication {
 
     <uses-feature android:name="android.hardware.nfc" android:required="true" />
 
-    <application ...>
+    <!--
+        tools:replace is required because the Halo SDK (and its bundled Visa library)
+        declare android:label and android:allowBackup in their own manifests.
+        Without these overrides the manifest merger will refuse to build.
+    -->
+    <application
+        ...
+        tools:replace="android:label,android:allowBackup">
         <activity
             android:name=".MainActivity"
             ...>
@@ -251,25 +226,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.
+Every call to the Halo SDK must include a valid JWT. The SDK requests one via the `onRequestJWT` callback whenever it needs to authenticate.
 
-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.
+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.
 
-> **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.
+Split your config and JWT supply into two files:
 
-**Recommended approach:** split credentials and JWT retrieval 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 +248,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 +321,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 +417,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
 
@@ -479,11 +425,9 @@ Below is a minimal but complete payment screen taken directly from the example a
 
 ```tsx
 // App.tsx
-import React, { useEffect, useState } from 'react';
+import { useEffect, useState } from 'react';
 import {
   ActivityIndicator,
-  PermissionsAndroid,
-  Platform,
   Text,
   TextInput,
   TouchableOpacity,
@@ -496,6 +440,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 +453,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 +583,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 +642,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
@@ -711,7 +667,6 @@ compileSdkVersion localProperties.getProperty('compileSdkVersion').toInteger()
 **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
 
@@ -726,6 +681,55 @@ 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: Manifest merger fails with an attribute conflict (e.g. `android:label`, `android:allowBackup`).**
+
+The Halo SDK bundles several sub-libraries (Visa Sensory Branding, etc.), each with their own `AndroidManifest.xml`. Any `processDebugMainManifest` failure caused by an attribute clash is fixed by adding the conflicting attribute name to `tools:replace` on your `<application>` element:
+
+```xml
+<application
+    ...
+    tools:replace="android:label,android:allowBackup">
+```
+
+If you add a new attribute to `tools:replace` and the **same error persists on the very next build**, Gradle may have cached the previously failed manifest merge. Run a clean build and try again:
+
+```bash
+cd android && ./gradlew clean
+```
+
+Then re run your normal build (`npx react-native run-android` or Android Studio).
+
+---
+
+**Q: TypeScript build errors about `customConditions` or `moduleResolution` after editing `tsconfig.json`.**
+
+Do not override `moduleResolution` in your project's `tsconfig.json`. The base `@react-native/typescript-config` sets `"moduleResolution": "bundler"`, which is the only value compatible with its `customConditions` setting. Overriding it to `"node"` causes a TypeScript error.
+
+Instead, extend the base config and only add project specific overrides:
+
+```json
+{
+  "extends": "@react-native/typescript-config/tsconfig.json",
+  "compilerOptions": {
+    "skipLibCheck": true
+  }
+}
+```
+
+`skipLibCheck: true` suppresses spurious type errors that originate inside `node_modules` (e.g. phantom `@types/react` v19 conflicts) without changing how your own code is compiled.
+
+---
+
+**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/android/src/main/AndroidManifest.xml

@@ -1,6 +1,8 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
+  xmlns:tools="http://schemas.android.com/tools"
   package="za.co.synthesis.halo.sdkreactnativeplugin">
-    <application>
+    <application
+        tools:replace="android:label,android:allowBackup">
         <activity
             android:name=".AnimationActivity"
             android:theme="@style/Theme.AppCompat.Light.NoActionBar"

package/package.json

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