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

package/src/index.tsx

@@ -1,12 +1,82 @@
+/**
+ * @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);
+ * ```
+ */
+
 import { Platform } from 'react-native';
 import Okhi from './NativeOkhi';
 import type { OkCollect, OkHiLogin, OkHiSuccessResponse } from './types';
-export type * from './types';
-
-export function multiply(a: number, b: number): number {
-  return Okhi.multiply(a, b);
-}
+import { OkHiException } from './types';
+export * from './types';
 
+/**
+ * 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
+ */
 export function login(credentials: OkHiLogin): Promise<string[] | null> {
   return new Promise((resolve) => {
     Okhi.login(credentials, (results) => {
@@ -39,7 +109,7 @@ function processVerificationResponse(
   response: unknown,
   error: unknown,
   resolve: (value: OkHiSuccessResponse) => void,
-  reject: (reason: { code: string; message: string }) => void
+  reject: (reason: OkHiException) => void
 ) {
   try {
     const res = response as { user: string; location: string };
@@ -49,25 +119,75 @@ function processVerificationResponse(
         location: JSON.parse(res.location),
       });
     } else if (error != null) {
-      const err = error as { code: string; message: string };
-      reject({
-        code: err.code,
-        message: err.message,
-      });
+      const err = error as { code?: string; message?: string };
+      reject(OkHiException.fromNativeError(err));
     } else {
-      reject({
-        code: 'unknown',
-        message: 'unable to complete operation - unknown response',
-      });
+      reject(
+        new OkHiException(OkHiException.UNKNOWN, 'An unknown error occurred')
+      );
     }
   } catch {
-    reject({
-      code: 'unknown',
-      message: 'unable to complete operation - unknown error',
-    });
+    reject(
+      new OkHiException(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
+ */
 export function startDigitalAddressVerification(
   okcollect?: OkCollect
 ): Promise<OkHiSuccessResponse> {
@@ -79,6 +199,43 @@ export function startDigitalAddressVerification(
   });
 }
 
+/**
+ * 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
+ */
 export function startPhysicalAddressVerification(
   okcollect?: OkCollect
 ): Promise<OkHiSuccessResponse> {
@@ -90,6 +247,47 @@ export function startPhysicalAddressVerification(
   });
 }
 
+/**
+ * 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
+ */
 export function startDigitalAndPhysicalAddressVerification(
   okcollect?: OkCollect
 ): Promise<OkHiSuccessResponse> {
@@ -104,6 +302,48 @@ export function startDigitalAndPhysicalAddressVerification(
   });
 }
 
+/**
+ * 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
+ */
 export function createAddress(
   okcollect?: OkCollect
 ): Promise<OkHiSuccessResponse> {
@@ -120,11 +360,11 @@ function processBooleanResponse(
   result: unknown,
   error: unknown,
   resolve: (value: boolean) => void,
-  reject: (reason: { code: string; message: string }) => void
+  reject: (reason: OkHiException) => void
 ) {
   if (error != null) {
-    const err = error as { code: string; message: string };
-    reject({ code: err.code, message: err.message });
+    const err = error as { code?: string; message?: string };
+    reject(OkHiException.fromNativeError(err));
   } else {
     resolve(result as boolean);
   }
@@ -135,18 +375,16 @@ function processStringResponse(
   result: unknown,
   error: unknown,
   resolve: (value: string) => void,
-  reject: (reason: { code: string; message: string }) => void
+  reject: (reason: OkHiException) => void
 ) {
   if (error != null) {
-    const err = error as { code: string; message: string };
-    reject({ code: err.code, message: err.message });
+    const err = error as { code?: string; message?: string };
+    reject(OkHiException.fromNativeError(err));
   } else {
     resolve(result as string);
   }
 }
 
-// MARK: - Check Helpers
-
 export function isLocationServicesEnabled(): Promise<boolean> {
   return new Promise((resolve, reject) => {
     Okhi.isLocationServicesEnabled((result, error) => {
@@ -218,8 +456,6 @@ export function openProtectedApps(): Promise<void> {
   });
 }
 
-// MARK: - Request Helpers
-
 export function requestLocationPermission(): Promise<boolean> {
   return new Promise((resolve, reject) => {
     Okhi.requestLocationPermission((result, error) => {
@@ -247,10 +483,12 @@ export function requestEnableLocationServices(): Promise<boolean> {
 export function requestPostNotificationPermissions(): Promise<boolean> {
   return new Promise((resolve, reject) => {
     if (Platform.OS === 'ios') {
-      reject({
-        code: 'unsupported_platform',
-        message: 'operation not supported',
-      });
+      reject(
+        new OkHiException(
+          OkHiException.UNSUPPORTED_DEVICE,
+          'Notification permission request is not supported on iOS. Use iOS-specific notification APIs.'
+        )
+      );
     } else {
       Okhi.requestPostNotificationPermissions((result, error) => {
         processBooleanResponse(result, error, resolve, reject);