react-native-okhi 1.2.32-beta.6 → 2.0.1

package/README.md

@@ -1,37 +1,177 @@
+<div align="left">
+
 # react-native-okhi
 
-The OkHi React Native library enables you to collect and verify addresses from your users
+[![npm version](https://img.shields.io/npm/v/react-native-okhi.svg?style=flat-square)](https://www.npmjs.com/package/react-native-okhi)
+[![license](https://img.shields.io/npm/l/react-native-okhi.svg?style=flat-square)](https://github.com/OkHi/react-native-okhi/blob/master/LICENSE)
+[![platform](https://img.shields.io/badge/platform-iOS%20%7C%20Android-lightgrey?style=flat-square)](#requirements)
+[![CI](https://img.shields.io/github/actions/workflow/status/OkHi/react-native-okhi/ci.yml?style=flat-square)](https://github.com/OkHi/react-native-okhi/actions/workflows/ci.yml)
+
+</div>
 
-## Installation
+## Quick Start
 
+### 1. Install
 
-```sh
+```bash
 npm install react-native-okhi
+# or
+yarn add react-native-okhi
 ```
 
+### 2. Configure native projects
 
-## Usage
+<details>
+<summary><b>iOS Setup</b></summary>
 
+Install pods:
 
-```js
-import { multiply } from 'react-native-okhi';
+```bash
+cd ios && pod install && cd ..
+```
 
-// ...
+Add to `Info.plist`:
 
-const result = multiply(3, 7);
+```xml
+<key>NSLocationWhenInUseUsageDescription</key>
+<string>Grant to enable creating addresses at your current location.</string>
+<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
+<string>Grant to enable creating and verifying your addresses.</string>
 ```
 
+Enable Background Modes in Xcode → Signing & Capabilities:
 
-## Contributing
+- ✅ Location updates
+- ✅ Background fetch
 
-- [Development workflow](CONTRIBUTING.md#development-workflow)
-- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
-- [Code of conduct](CODE_OF_CONDUCT.md)
+Add to `AppDelegate.mm`:
 
-## License
+```objc
+@import OkHi;
+
+- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
+{
+  [OK startMonitoring];
+  // ... rest of your code
+}
+```
+
+If using swift `AppDelegate.swift`:
+
+```swift
+import OkHi
 
-MIT
+@main
+class AppDelegate: UIResponder, UIApplicationDelegate {
 
----
+  func application(
+    _ application: UIApplication,
+    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
+  ) -> Bool {
+
+    OK.startMonitoring() // add this
+    return true
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Android Setup</b></summary>
+
+Add OkHi Maven repository to `android/build.gradle`:
+
+```gradle
+allprojects {
+    repositories {
+        maven { url "https://repo.okhi.io/artifactory/maven" }
+    }
+}
+```
+
+Add permissions to `AndroidManifest.xml`:
+
+```xml
+<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" />
+<uses-permission android:name="android.permission.INTERNET" />
+<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE" android:foregroundServiceType="location" />
+```
+
+</details>
+
+<details>
+<summary><b>Expo Setup</b></summary>
+
+> **Note:** Requires a development build. This library won't work with Expo Go.
+
+```bash
+npx expo install react-native-okhi@beta
+npx expo prebuild
+npx expo run:ios  # or run:android
+```
+
+</details>
+
+### 3. Verify an address
+
+```typescript
+import * as OkHi from 'react-native-okhi';
+
+// Step 1
+await OkHi.login({
+  auth: {
+    branchId: 'YOUR_BRANCH_ID',
+    clientKey: 'YOUR_CLIENT_KEY',
+  },
+  user: {
+    firstName: 'John',
+    lastName: 'Doe',
+    phone: '+254712345678',
+    email: 'john@example.com',
+  },
+});
+
+// Step 2
+const { user, location } = await OkHi.startDigitalAddressVerification();
+```
+
+### Full Example
+
+```tsx
+import { Button, Text, View } from 'react-native';
+import * as OkHi from 'react-native-okhi';
+
+export default function Dashboard() {
+  useEffect(() => {
+    OkHi.login({
+      auth: { branchId: 'YOUR_BRANCH_ID', clientKey: 'YOUR_CLIENT_KEY' },
+      user: {
+        firstName: 'John',
+        lastName: 'Doe',
+        phone: '+254712345678',
+        email: 'john@example.com',
+      },
+    }).then(() => console.log('user logged in'));
+  }, []);
+
+  const onButtonPress = async () => {
+    const { user, location } = await OkHi.startDigitalAddressVerification();
+    console.log(`started verification for: ${location.id}`);
+  };
+
+  return (
+    <View style={{ flex: 1, justifyContent: 'center', padding: 20 }}>
+      <Button title="Verify Address" onPress={onButtonPress} />
+    </View>
+  );
+}
+```
+
+## License
 
-Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)
+MIT © [OkHi](https://okhi.co)

package/ReactNativeOkhi.podspec

@@ -16,6 +16,6 @@ Pod::Spec.new do |s|
   s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
   s.private_header_files = "ios/**/*.h"
 
-  s.dependency "OkHi", "1.10.6"
+  s.dependency "OkHi", "1.10.9"
   install_modules_dependencies(s)
 end

package/android/build.gradle

@@ -73,7 +73,7 @@ repositories {
 def kotlin_version = getExtOrDefault("kotlinVersion")
 
 dependencies {
-  implementation 'io.okhi.android:okhi:1.0.0'
+  implementation 'io.okhi.android:okhi:1.0.5'
   implementation "com.facebook.react:react-android"
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
 }

package/android/src/main/java/com/okhi/OkhiModule.kt

@@ -50,10 +50,6 @@ class OkhiModule(reactContext: ReactApplicationContext) : NativeOkhiSpec(reactCo
     return NAME
   }
 
-  override fun multiply(a: Double, b: Double): Double {
-    return a * b
-  }
-
   override fun login(credentials: ReadableMap?, callback: Callback?) {
     if (credentials == null) {
       callback?.invoke(null)

package/ios/OkHiWrapper.swift

@@ -17,10 +17,6 @@ import UserNotifications
     okVerify.delegate = self
   }
   
-  @objc public static func multiply(_ a: Double, _ b: Double) -> NSNumber {
-    return NSNumber(value: a * b)
-  }
-  
   @objc public static func login(_ credentials: NSDictionary, callback: @escaping ([String]?) -> Void) {
     // Extract auth dictionary
     guard let authDict = credentials["auth"] as? NSDictionary,
@@ -54,7 +50,7 @@ import UserNotifications
     let auth = OkHiAuth(
       branchId: branchId,
       clientKey: clientKey,
-      environment: env == "prod" ? .prod : .sandbox,
+      environment: env,
       appContext: nativeAppContext
     )
     

package/ios/Okhi.mm

@@ -8,10 +8,6 @@
 #endif
 
 @implementation Okhi
-- (NSNumber *)multiply:(double)a b:(double)b {
-    return [OkHiWrapper multiply:a :b];
-}
-
 - (void)login:(NSDictionary *)credentials callback:(RCTResponseSenderBlock)callback {
     [OkHiWrapper login:credentials callback:^(NSArray<NSString *> *results) {
         if (callback) {

package/lib/commonjs/NativeOkhi.js.map

@@ -1 +1 @@
-{"version":3,"names":["_reactNative","require","_default","exports","default","TurboModuleRegistry","getEnforcing"],"sourceRoot":"../../src","sources":["NativeOkhi.ts"],"mappings":";;;;;;AAAA,IAAAA,YAAA,GAAAC,OAAA;AAAqE,IAAAC,QAAA,GAAAC,OAAA,CAAAC,OAAA,GAmEtDC,gCAAmB,CAACC,YAAY,CAAO,MAAM,CAAC","ignoreList":[]}
+{"version":3,"names":["_reactNative","require","_default","exports","default","TurboModuleRegistry","getEnforcing"],"sourceRoot":"../../src","sources":["NativeOkhi.ts"],"mappings":";;;;;;AAAA,IAAAA,YAAA,GAAAC,OAAA;AAAqE,IAAAC,QAAA,GAAAC,OAAA,CAAAC,OAAA,GAkEtDC,gCAAmB,CAACC,YAAY,CAAO,MAAM,CAAC","ignoreList":[]}

package/lib/commonjs/index.js

@@ -3,6 +3,26 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+var _exportNames = {
+  login: true,
+  startDigitalAddressVerification: true,
+  startPhysicalAddressVerification: true,
+  startDigitalAndPhysicalAddressVerification: true,
+  createAddress: true,
+  isLocationServicesEnabled: true,
+  canOpenProtectedApps: true,
+  getLocationAccuracyLevel: true,
+  isBackgroundLocationPermissionGranted: true,
+  isCoarseLocationPermissionGranted: true,
+  isFineLocationPermissionGranted: true,
+  isPlayServicesAvailable: true,
+  isPostNotificationPermissionGranted: true,
+  openProtectedApps: true,
+  requestLocationPermission: true,
+  requestBackgroundLocationPermission: true,
+  requestEnableLocationServices: true,
+  requestPostNotificationPermissions: true
+};
 exports.canOpenProtectedApps = canOpenProtectedApps;
 exports.createAddress = createAddress;
 exports.getLocationAccuracyLevel = getLocationAccuracyLevel;
@@ -13,7 +33,6 @@ exports.isLocationServicesEnabled = isLocationServicesEnabled;
 exports.isPlayServicesAvailable = isPlayServicesAvailable;
 exports.isPostNotificationPermissionGranted = isPostNotificationPermissionGranted;
 exports.login = login;
-exports.multiply = multiply;
 exports.openProtectedApps = openProtectedApps;
 exports.requestBackgroundLocationPermission = requestBackgroundLocationPermission;
 exports.requestEnableLocationServices = requestEnableLocationServices;
@@ -24,10 +43,92 @@ exports.startDigitalAndPhysicalAddressVerification = startDigitalAndPhysicalAddr
 exports.startPhysicalAddressVerification = startPhysicalAddressVerification;
 var _reactNative = require("react-native");
 var _NativeOkhi = _interopRequireDefault(require("./NativeOkhi"));
+var _types = require("./types");
+Object.keys(_types).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _types[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _types[key];
+    }
+  });
+});
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-function multiply(a, b) {
-  return _NativeOkhi.default.multiply(a, b);
-}
+/**
+ * @packageDocumentation
+ * React Native OkHi SDK
+ *
+ * A comprehensive React Native library for address verification using OkHi's
+ * digital and physical verification methods.
+ *
+ * @example
+ * ```typescript
+ * import * as OkHi from 'react-native-okhi';
+ *
+ * // 1. Login
+ * await OkHi.login({
+ *   auth: { branchId: 'xxx', clientKey: 'xxx' },
+ *   user: { firstName: 'John', lastName: 'Doe', phone: '+254...', email: '...' },
+ * });
+ *
+ * // 2. Start verification
+ * const result = await OkHi.startDigitalAddressVerification();
+ * console.log('Verified address:', result.location.formattedAddress);
+ * ```
+ */
+
+/**
+ * Authenticates a user with the OkHi platform.
+ *
+ * @remarks
+ * This must be called before any verification functions. It establishes
+ * the user session and validates your API credentials.
+ *
+ * **When to call login:** The login function should be called once you have
+ * an authenticated user in your app. A common place to call login is immediately
+ * after the app dashboard is rendered, for example in a banking app after a user
+ * successfully signs in.
+ *
+ * It initializes OkHi and enables your users to resume verification if they
+ * switch devices, as well as enables re-verification of previously unknown addresses.
+ *
+ * The login persists for the duration of the app session.
+ *
+ * @param credentials - The login configuration containing auth credentials and user info
+ * @returns A promise that resolves with an array of permission strings that were granted,
+ *          or `null` if `withPermissionsRequest` was not enabled
+ *
+ * @example
+ * ```typescript
+ * import * as OkHi from 'react-native-okhi';
+ * import type { OkHiLogin } from 'react-native-okhi';
+ *
+ * const credentials: OkHiLogin = {
+ *   auth: {
+ *     branchId: 'your_branch_id',
+ *     clientKey: 'your_client_key',
+ *   },
+ *   user: {
+ *     firstName: 'John',
+ *     lastName: 'Doe',
+ *     phone: '+254712345678',
+ *     email: 'john.doe@example.com',
+ *   },
+ * };
+ *
+ * try {
+ *   await OkHi.login(credentials);
+ *   console.log('Login successful');
+ * } catch (error) {
+ *   console.error('Login failed:', error);
+ * }
+ * ```
+ *
+ * @see {@link OkHiLogin} - Configuration type
+ * @see {@link startDigitalAddressVerification} - Call after login to verify addresses
+ */
 function login(credentials) {
   return new Promise(resolve => {
     _NativeOkhi.default.login(credentials, results => {
@@ -64,23 +165,70 @@ function processVerificationResponse(response, error, resolve, reject) {
       });
     } else if (error != null) {
       const err = error;
-      reject({
-        code: err.code,
-        message: err.message
-      });
+      reject(_types.OkHiException.fromNativeError(err));
     } else {
-      reject({
-        code: 'unknown',
-        message: 'unable to complete operation - unknown response'
-      });
+      reject(new _types.OkHiException(_types.OkHiException.UNKNOWN, 'An unknown error occurred'));
     }
   } catch {
-    reject({
-      code: 'unknown',
-      message: 'unable to complete operation - unknown error'
-    });
+    reject(new _types.OkHiException(_types.OkHiException.UNKNOWN, 'An unknown error occurred'));
   }
 }
+
+/**
+ * @remarks
+ * Starts the digital address verification flow.
+ *
+ * **Prerequisites:**
+ * - Must call {@link login} first
+ *
+ * @param okcollect - Optional configuration for styling and behavior
+ * @returns A promise that resolves with the user and location data
+ *
+ * @example
+ * ```typescript
+ * import * as OkHi from 'react-native-okhi';
+ *
+ * // Basic usage with defaults
+ * const result = await OkHi.startDigitalAddressVerification();
+ * console.log('Address:', result.location.formattedAddress);
+ * console.log('Location ID:', result.location.id);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import * as OkHi from 'react-native-okhi';
+ * import type { OkCollect } from 'react-native-okhi';
+ *
+ * // With custom styling
+ * const config: OkCollect = {
+ *   style: {
+ *     color: '#FF5722',
+ *     logo: 'https://example.com/logo.png',
+ *   },
+ *   configuration: {
+ *     streetView: true,
+ *   },
+ * };
+ *
+ * const result = await OkHi.startDigitalAddressVerification(config);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import * as OkHi from 'react-native-okhi';
+ *
+ * // Start verification on previously created address
+ * const locationId: string = await fetchLocationIDFromMyDB()
+ * const result = await OkHi.startDigitalAddressVerification({
+ *   locationId: locationId,
+ * });
+ * ```
+ *
+ * @see {@link OkCollect} - Configuration options
+ * @see {@link OkHiSuccessResponse} - Return type
+ * @see {@link startPhysicalAddressVerification} - For physical verification
+ * @see {@link startDigitalAndPhysicalAddressVerification} - For combined verification
+ */
 function startDigitalAddressVerification(okcollect) {
   const config = buildConfig(okcollect);
   return new Promise((resolve, reject) => {
@@ -89,6 +237,44 @@ function startDigitalAddressVerification(okcollect) {
     });
   });
 }
+
+/**
+ * Starts the physical address verification flow.
+ *
+ * @remarks
+ * Physical verification requires an agent to visit the user's location
+ * in person.
+ *
+ * **Prerequisites:**
+ * - Must call {@link login} first
+ *
+ * @param okcollect - Optional configuration for styling and behavior
+ * @returns A promise that resolves with the user and location data
+ *
+ * @example
+ * ```typescript
+ * import * as OkHi from 'react-native-okhi';
+ *
+ * const result = await OkHi.startPhysicalAddressVerification();
+ * console.log('Verification requested for:', result.location.formattedAddress);
+ * console.log('Location ID for tracking:', result.location.id);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import * as OkHi from 'react-native-okhi';
+ *
+ * // With custom configuration
+ * const result = await OkHi.startPhysicalAddressVerification({
+ *   style: { color: '#2196F3' },
+ * });
+ * ```
+ *
+ * @see {@link OkCollect} - Configuration options
+ * @see {@link OkHiSuccessResponse} - Return type
+ * @see {@link startDigitalAddressVerification} - For instant digital verification
+ * @see {@link startDigitalAndPhysicalAddressVerification} - For combined verification
+ */
 function startPhysicalAddressVerification(okcollect) {
   const config = buildConfig(okcollect);
   return new Promise((resolve, reject) => {
@@ -97,6 +283,48 @@ function startPhysicalAddressVerification(okcollect) {
     });
   });
 }
+
+/**
+ * Starts both digital and physical address verification flows.
+ *
+ * @remarks
+ * This combines both verification methods for maximum confidence.
+ *
+ * **Prerequisites:**
+ * - Must call {@link login} first
+ *
+ * @param okcollect - Optional configuration for styling and behavior
+ * @returns A promise that resolves with the user and location data
+ *
+ * @example
+ * ```typescript
+ * import * as OkHi from 'react-native-okhi';
+ *
+ * const result = await OkHi.startDigitalAndPhysicalAddressVerification();
+ * console.log('Physical + Digital Verification started for:', result.location.id);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import * as OkHi from 'react-native-okhi';
+ *
+ * // With full customization
+ * const result = await OkHi.startDigitalAndPhysicalAddressVerification({
+ *   style: {
+ *     color: '#4CAF50',
+ *     logo: 'https://example.com/logo.png',
+ *   },
+ *   configuration: {
+ *     streetView: true,
+ *   },
+ * });
+ * ```
+ *
+ * @see {@link OkCollect} - Configuration options
+ * @see {@link OkHiSuccessResponse} - Return type
+ * @see {@link startDigitalAddressVerification} - For digital-only verification
+ * @see {@link startPhysicalAddressVerification} - For physical-only verification
+ */
 function startDigitalAndPhysicalAddressVerification(okcollect) {
   const config = buildConfig(okcollect);
   return new Promise((resolve, reject) => {
@@ -105,6 +333,49 @@ function startDigitalAndPhysicalAddressVerification(okcollect) {
     });
   });
 }
+
+/**
+ * Creates an address without starting verification.
+ *
+ * @remarks
+ * Use this when you want to collect and store an address but defer
+ * verification to a later time. The address can
+ * be verified later using the returned `locationId`.
+ *
+ * **Prerequisites:**
+ * - Must call {@link login} first
+ *
+ * @param okcollect - Optional configuration for styling and behavior
+ * @returns A promise that resolves with the user and location data
+ *
+ * @example
+ * ```typescript
+ * import * as OkHi from 'react-native-okhi';
+ *
+ * // Create address without verification
+ * const result = await OkHi.createAddress();
+ * console.log('Address created:', result.location.id);
+ *
+ * // Save the location ID to verify later
+ * const locationId = result.location.id;
+ * await saveToDatabase({ locationId: locationId });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import * as OkHi from 'react-native-okhi';
+ *
+ * // Later, verify the saved address
+ * const savedLocationId = await fetchLocationIdFromMyDB();
+ * const result = await OkHi.startDigitalAddressVerification({
+ *   locationId: savedLocationId,
+ * });
+ * ```
+ *
+ * @see {@link OkCollect} - Configuration options
+ * @see {@link OkHiSuccessResponse} - Return type
+ * @see {@link startDigitalAddressVerification} - To verify an address
+ */
 function createAddress(okcollect) {
   const config = buildConfig(okcollect);
   return new Promise((resolve, reject) => {
@@ -118,10 +389,7 @@ function createAddress(okcollect) {
 function processBooleanResponse(result, error, resolve, reject) {
   if (error != null) {
     const err = error;
-    reject({
-      code: err.code,
-      message: err.message
-    });
+    reject(_types.OkHiException.fromNativeError(err));
   } else {
     resolve(result);
   }
@@ -131,17 +399,11 @@ function processBooleanResponse(result, error, resolve, reject) {
 function processStringResponse(result, error, resolve, reject) {
   if (error != null) {
     const err = error;
-    reject({
-      code: err.code,
-      message: err.message
-    });
+    reject(_types.OkHiException.fromNativeError(err));
   } else {
     resolve(result);
   }
 }
-
-// MARK: - Check Helpers
-
 function isLocationServicesEnabled() {
   return new Promise((resolve, reject) => {
     _NativeOkhi.default.isLocationServicesEnabled((result, error) => {
@@ -204,9 +466,6 @@ function openProtectedApps() {
     resolve();
   });
 }
-
-// MARK: - Request Helpers
-
 function requestLocationPermission() {
   return new Promise((resolve, reject) => {
     _NativeOkhi.default.requestLocationPermission((result, error) => {
@@ -231,10 +490,7 @@ function requestEnableLocationServices() {
 function requestPostNotificationPermissions() {
   return new Promise((resolve, reject) => {
     if (_reactNative.Platform.OS === 'ios') {
-      reject({
-        code: 'unsupported_platform',
-        message: 'operation not supported'
-      });
+      reject(new _types.OkHiException(_types.OkHiException.UNSUPPORTED_DEVICE, 'Notification permission request is not supported on iOS. Use iOS-specific notification APIs.'));
     } else {
       _NativeOkhi.default.requestPostNotificationPermissions((result, error) => {
         processBooleanResponse(result, error, resolve, reject);