react-native-kalapa-ekyc 1.2.9 → 1.2.10

package/README.md

@@ -1,37 +1,59 @@
 # Kalapa eKYC React Native SDK Documentation
 
 Complete guide for integrating Kalapa eKYC functionality into your React Native applications.
+
 ---
+
 ## Changelog
+
+### 1.2.10
+- **Android**: Fix switch fall-through in `onError` callback — prevents Promise being rejected multiple times
+- **Android**: Fix `getCurrentActivity() == null` case now rejects Promise with `ACTIVITY_NULL` instead of leaving it pending forever
+- **Android**: Fix native crash when optional config keys are missing — all boolean/int fields now use safe `hasKey` guards
+- **Android**: SDK now runs on UI thread to safely open Activity
+- **Android**: Bump `compileSdkVersion` and `targetSdkVersion` to 35
+- **iOS**: Fix `handleResult` crash when `ocr_data.data.fields` is nil (e.g. `nfc_only` flow)
+- **iOS**: Fix `qr_code` response format — now correctly wrapped as `{ data: { decoded_text } }` to match TypeScript parser
+- **iOS**: Unify `EventSessionExpired` error code to `EXPIRED` (was `UNAUTHORIZED`)
+- **TypeScript**: `config` parameter is now fully typed (`KalapaEkycConfig`), no more `any`
+- **TypeScript**: `flow` parameter is now typed as `KalapaEkycFlow` union
+- **TypeScript**: Added `KalapaEkycErrorCode` union type for all error codes
+- **TypeScript**: Native module linkage guard — throws descriptive error with fix instructions if autolinking fails
+- **TypeScript**: `nfc_data` parser now handles camelCase field names from Android (`idNumber`, `dateOfBirth`, etc.)
+
 ### 1.2.9
 - **React-Native**: Add `customer_language` into config.
-- **Android**: Fix obfuscation error 
+- **Android**: Fix obfuscation error
+
 ### 1.2.8
 - **Android**: Update stable version for NFC step.
+
 ### 1.2.7
 - **Android**: Update config to scan QR code or not.
-- **React-Native**: Introduce config require_qr in AppConfig
+- **React-Native**: Introduce config `require_qr` in AppConfig
+
 ### 1.2.6
 - **Android**: Minor update, UI / UX optimize. Stable version
+
 ### 1.2.5
 - **Android**: Fix NFC step error UNKNOWN rarely happens on some device like Samsung Note 10
+
 ### 1.2.4
 - **Android**: Optimize UI / UX in NFC step
-- **React-Native**: show to skip / show confirm screen. 
+- **React-Native**: show to skip / show confirm screen.
+
 ### 1.2.3
 - **Android**: Optimize UI / UX in NFC step
+
 ### 1.2.2
 - **iOS**: Maintain UI config
 - **Android**: Maintain / Optimize NFC step
+
 ### 1.2.1
 - **successColor / failureColor**: Now can be configured via sdkConfig
+
 ### 1.2.0
 - **Documentation**: Complete overhaul of KalapaResult class documentation
-- **Documentation**: Added comprehensive property documentation for all root-level fields
-- **Documentation**: Added AddressEntities, MrzData, and QrCode object documentation
-- **Documentation**: Enhanced usage examples with all available properties
-- **Documentation**: Fixed package name references throughout documentation
-- **Documentation**: Added examples for accessing MRZ data, QR code data, and address entities
 
 ### 1.1.3
 - **Android**: Removed GIF dependencies to satisfy Google Play requirement (16KB pages size)
@@ -58,18 +80,23 @@ Complete guide for integrating Kalapa eKYC functionality into your React Native
 
 ## Requirements
 
-### React Native
+### Version Matrix
 
-```json
-"react": "17.0.2"
-"react-native": "0.66.3"
-```
+| Dependency | Version |
+|---|---|
+| React Native | >= 0.66 |
+| Android `minSdkVersion` | 24 |
+| Android `compileSdkVersion` | 35 |
+| Android `targetSdkVersion` | 35 |
+| iOS Deployment Target | >= 13.0 |
+| Kalapa Android SDK | 2.11.8 |
 
 ### Android
 
 **Minimum SDK Requirements:**
 - `minSdkVersion = 24`
-- `targetSdkVersion = 33`
+- `compileSdkVersion = 35`
+- `targetSdkVersion = 35`
 - `android.useAndroidX = true`
 - `Kotlin = 1.8.0+`
 
@@ -83,7 +110,7 @@ compileOptions {
 
 ### iOS
 
-- iOS Development Target >= 13.4
+- iOS Deployment Target >= 13.0
 
 ---
 
@@ -105,11 +132,11 @@ npm install react-native-kalapa-ekyc
 
 #### Manual Installation
 
-Add to your `app/package.json`:
+Add to your `package.json`:
 
 ```json
 "dependencies": {
-    "react-native-kalapa-ekyc": "^1.2.9"
+    "react-native-kalapa-ekyc": "^1.2.10"
 }
 ```
 
@@ -151,7 +178,7 @@ Add the **Near Field Communication Tag Reading** capability to your project targ
 Each eKYC profile requires a unique session ID (JWT access token). The SDK uses this session ID to perform all eKYC steps.
 
 **Important Notes:**
-- Failure to provide a valid session ID results in an unauthorized error
+- Failure to provide a valid session ID results in an `EXPIRED` error
 - Sessions are valid for 10 minutes by default (adjustable)
 - Each session ID should be used for a single eKYC flow
 
@@ -161,63 +188,57 @@ Check the [API documentation](https://www.notion.so/Init-session-820a772b8402499
 
 ### 2. Define SDK Configuration
 
-#### Basic Configuration Structure
-
-```jsx
-let configInfo = {
-    domain: <BASE_URL>,
-    main_color: <MAIN_COLOR>,
-    main_text_color: <MAIN_TEXT_COLOR>,
-    btn_text_color: <BTN_TEXT_COLOR>,
-    background_color: <BG_COLOR>,
-    success_color: <SUCCESS_COLOR>,
-    failure_color: <FAILURE_COLOR>,
-    language: <LANGUAGE>,
-    liveness_version: <LIVENESS_VERSION>,
-    face_data: <FACE_DATA>,
-    mrz: <INPUT_MRZ>,
-    qr_code: <INPUT_QR_CODE>,
-    allow_mrz_rescan_on_nfc_mismatch: <ALLOW_MRZ_RESCAN_ON_NFC_MISMATCH>,
-    with_confirm_screen: <WITH_CONFIRM_SCREEN>,
-    require_qr: <REQUIRE_QR>,
-    customer_language: <CUSTOMER_LANGUAGE>
-}
+#### TypeScript Interface
+
+```typescript
+import KalapaEkyc, { KalapaEkycConfig, KalapaEkycFlow } from 'react-native-kalapa-ekyc';
+
+const configInfo: KalapaEkycConfig = {
+    domain: 'https://ekyc-sdk.kalapa.vn',
+    main_color: '#1F69E6',
+    main_text_color: '#000000',
+    btn_text_color: '#FFFFFF',
+    background_color: '#FFFFFF',
+    success_color: '#388E3C',
+    failure_color: '#F44336',
+    language: 'vi',
+    liveness_version: 3,
+    with_confirm_screen: true,
+    require_qr: false,
+    allow_mrz_rescan_on_nfc_mismatch: true,
+};
 ```
 
 #### Configuration Parameters
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `BASE_URL` | String | Base URL for SDK API requests. Example endpoints: `<BASE_URL>/api/kyc/scan-front`, `<BASE_URL>/api/kyc/scan-back` |
-| `BG_COLOR` | String | Hex color code for SDK background |
-| `MAIN_COLOR` | String | Hex color code for buttons and functional texts |
-| `MAIN_TEXT_COLOR` | String | Hex color code for main text elements |
-| `BTN_TEXT_COLOR` | String | Hex color code for text inside filled buttons |
-| `SUCCESS_COLOR` | String | Hex color code for text and view that indicated for success state |
-| `FAILURE_COLOR` | String | Hex color code for text and view that indicated for failure state |
-| `LIVENESS_VERSION` | Integer | Liveness detection version:<br/>• `3` - Requires 3 random actions (turn left/right/up/down, tilt left/right)<br/>• `2` - Move face towards camera<br/>• `1` - No action required |
-| `LANGUAGE` | String | UI language: `"vi"` (Vietnamese) or `"en"` (English) |
-| `FACE_DATA` | String | Base64 face data. If valid, skips liveness step and uses this for comparison with NFC portrait or document portrait |
-| `INPUT_MRZ` | String | Pre-filled MRZ data. If valid, skips MRZ scan step. Invalid input throws `INVALID_MRZ` error |
-| `INPUT_QR_CODE` | String | Pre-filled QR code. If valid, skips QR scan step. Invalid input throws `INVALID_QR` error |
-| `ALLOW_MRZ_RESCAN_ON_NFC_MISMATCH` | Boolean | If `true`, allows user to rescan MRZ when chip data doesn't match input MRZ |
-| `WITH_CONFIRM_SCREEN` | Boolean | If `true`, allows user to enter confirm step |
-| `REQUIRE_QR` | Boolean | If `true`, SDK will scan for QR Code and may reduce the MRZ step when enter the NFC step. |
-| `CUSTOMER_LANGUAGE` | String | Default "", If you want to custom your own language, contact Kalapa in order to use this feature. |
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `domain` | string | `https://ekyc-sdk.kalapa.vn` | Base URL for SDK API requests |
+| `main_color` | string | `#1F69E6` | Hex color for buttons and primary UI elements |
+| `main_text_color` | string | `#000000` | Hex color for main text |
+| `btn_text_color` | string | `#FFFFFF` | Hex color for text inside filled buttons |
+| `background_color` | string | `#FFFFFF` | Hex color for SDK background |
+| `success_color` | string | `#388E3C` | Hex color for success state indicators |
+| `failure_color` | string | `#F44336` | Hex color for failure state indicators |
+| `language` | `'vi'` \| `'en'` | `'en'` | SDK UI language |
+| `customer_language` | string | `''` | Custom language key — contact Kalapa to enable |
+| `liveness_version` | `1` \| `2` \| `3` | `0` | Liveness detection version: `3` = 3 random actions, `2` = move face toward camera, `1` = no action |
+| `face_data` | string | — | Base64 face data. If valid, skips liveness step |
+| `mrz` | string | — | Pre-filled MRZ. If valid, skips MRZ scan. Invalid input throws `MRZ_INVALID` |
+| `qr_code` | string | — | Pre-filled QR code. If valid, skips QR scan |
+| `allow_mrz_rescan_on_nfc_mismatch` | boolean | `false` | Allow user to rescan MRZ when NFC chip data doesn't match |
+| `with_confirm_screen` | boolean | `false` | Show confirm screen before submitting |
+| `require_qr` | boolean | `false` | Require QR code scan — may reduce the MRZ step in NFC flow |
+| `session_id` | string | — | Resume a previous leftover session |
+
 ---
 
 ### 3. Define the SDK Flow
 
-#### Available eKYC Steps
-
-1. Scan the document
-2. Scan the face
-3. Scan the NFC chip
-
 #### Flow Types
 
-| Flow Type | Scan Document | Scan Face | Scan NFC Chip |
-|-----------|---------------|-----------|---------------|
+| Flow | Scan Document | Scan Face | Scan NFC Chip |
+|------|:---:|:---:|:---:|
 | `ekyc` | ✓ | ✓ | ✗ |
 | `nfc_ekyc` | ✓ | ✓ | ✓ |
 | `nfc_only` | ✗ | ✓ | ✓ |
@@ -226,11 +247,8 @@ let configInfo = {
 
 The SDK flow typically matches the flow set during session creation. However, there are special use cases:
 
-**Example Use Case for `nfc_only`:**
-If users completed the basic `ekyc` flow but failed to scan the NFC chip, you can:
-- Reuse the same session ID
-- Set flow to `nfc_only`
-- Allow NFC chip scanning without re-scanning document and face
+**Example — `nfc_only` retry:**
+If a user completed `ekyc` but failed the NFC scan, you can reuse the same session ID with `nfc_only` to allow NFC scanning without re-scanning the document and face.
 
 **Best Practice:** Use separate sessions for different flows to simplify data management.
 
@@ -238,53 +256,64 @@ If users completed the basic `ekyc` flow but failed to scan the NFC chip, you ca
 
 ### 4. Start the SDK
 
-```jsx
-import KalapaEkyc, { KalapaResult } from 'react-native-kalapa-ekyc';
+```typescript
+import KalapaEkyc, { KalapaResult, KalapaEkycConfig, KalapaEkycFlow } from 'react-native-kalapa-ekyc';
+
+const configInfo: KalapaEkycConfig = {
+    domain: 'https://ekyc-sdk.kalapa.vn',
+    language: 'vi',
+    liveness_version: 3,
+    with_confirm_screen: true,
+};
 
-let sessionId = yourSessionInitFunc();
-let sdkFlow = "<YOUR_SDK_FLOW>"; // ekyc / nfc_ekyc / nfc_only
-let configInfo = {...};
-
-KalapaEkyc.start(sessionId, sdkFlow, configInfo)
-    .then((rawResult) => {
-        try {
-            // You can use either the constructor or static method
-            const result = KalapaResult.fromRawResult(rawResult);
-            // Or: const result = new KalapaResult(rawResult);
-            handleSuccessfulResult(result);
-        } catch (error) {
-            console.error("Result parsing error:", error);
+const flow: KalapaEkycFlow = 'nfc_ekyc';
+
+KalapaEkyc.start(sessionId, flow, configInfo)
+    .then(({ kalapa_result }) => {
+        const result: KalapaResult = kalapa_result;
+
+        if (result.isApproved()) {
+            // Store or display non-sensitive fields
+            saveVerificationResult({
+                decision: result.decision,
+                session: result.session,
+                idNumberMasked: result.id_number.replace(/.(?=.{4})/g, '*'),
+            });
+        } else if (result.isManualReview()) {
+            // Notify backend for manual review
         }
     })
     .catch((error) => {
         switch (error.code) {
-            case "EXPIRED":
-                console.warn("Session expired:", error.message);
+            case 'EXPIRED':
+                // Prompt user to restart — session timed out
+                break;
+            case 'CANCELED':
+                // User backed out — no action needed
                 break;
-            case "CANCELED":
-                console.warn("User canceled:", error.message);
+            case 'PERMISSION_DENIED':
+                // Guide user to grant camera/NFC permission in Settings
                 break;
-            case "PERMISSION_DENIED":
-                console.error("Permission denied:", error.message);
+            case 'DEVICE_NOT_ACCEPTABLE':
+                // Block flow — emulator, rooted, or jailbroken device
                 break;
-            case "DEVICE_NOT_ACCEPTABLE":
-                console.error("Device not acceptable:", error.message);
+            case 'MRZ_INVALID':
+                // Invalid pre-filled MRZ was passed in config
                 break;
-            case "MRZ_INVALID":
-                console.error("Invalid MRZ:", error.message);
+            case 'NFC_NOT_MATCH':
+                // NFC chip data doesn't match scanned document
                 break;
-            case "NFC_NOT_MATCH":
-                console.error("NFC mismatch:", error.message);
+            case 'UNSUPPORTED':
+                // Device doesn't support NFC
                 break;
-            case "UNSUPPORTED":
-                console.error("Unsupported device:", error.message);
+            case 'CONFIG_ERROR':
+                // Invalid domain, session, or SDK config
                 break;
-            case "CONFIG_ERROR":
-                console.error("Configuration error:", error.message);
+            case 'ACTIVITY_NULL':
+                // Android only — app was backgrounded when SDK launched
                 break;
-            case "OTHER":
+            case 'OTHER':
             default:
-                console.error("Unknown error:", error.message);
                 break;
         }
     });
@@ -296,17 +325,18 @@ KalapaEkyc.start(sessionId, sdkFlow, configInfo)
 
 ### Error Codes
 
-| Error Code | Description |
-|------------|-------------|
-| `EXPIRED` | Session expired (10 minutes timeout) |
-| `CANCELED` | User canceled the eKYC process |
-| `PERMISSION_DENIED` | Camera or NFC permission denied |
-| `DEVICE_NOT_ACCEPTABLE` | Emulator, rooted, or jailbroken device detected |
-| `MRZ_INVALID` | Input MRZ is invalid |
-| `NFC_NOT_MATCH` | MRZ doesn't match NFC chip data |
-| `UNSUPPORTED` | Device doesn't support required features (usually NFC) |
-| `CONFIG_ERROR` | Configuration error |
-| `OTHER` | Unexpected error |
+| Error Code | Platform | Description |
+|------------|----------|-------------|
+| `EXPIRED` | Android, iOS | Session expired (default 10-minute timeout) |
+| `CANCELED` | Android, iOS | User canceled the eKYC process |
+| `PERMISSION_DENIED` | Android | Camera or NFC permission denied |
+| `DEVICE_NOT_ACCEPTABLE` | Android | Emulator, rooted, or virtual camera detected |
+| `MRZ_INVALID` | Android | Pre-filled MRZ input is invalid |
+| `NFC_NOT_MATCH` | Android | MRZ does not match NFC chip data |
+| `UNSUPPORTED` | Android, iOS | Device doesn't support required features (NFC) |
+| `CONFIG_ERROR` | Android, iOS | Domain, session, or SDK configuration error |
+| `ACTIVITY_NULL` | Android | App Activity was null when SDK tried to launch |
+| `OTHER` | Android, iOS | Unexpected error |
 
 ---
 
@@ -314,103 +344,79 @@ KalapaEkyc.start(sessionId, sdkFlow, configInfo)
 
 ### KalapaResult Class
 
-The SDK provides a `KalapaResult` class for type-safe data access:
+The SDK returns a `KalapaResult` instance in the resolved value of `start()`. No manual parsing is needed.
 
 ```typescript
-import { KalapaResult } from 'react-native-kalapa-ekyc';
-
-// Create instance using static method (recommended)
-const result = KalapaResult.fromRawResult(rawResult);
+import KalapaEkyc, { KalapaResult } from 'react-native-kalapa-ekyc';
 
-// Or use constructor directly
-const result = new KalapaResult(rawResult);
+const { kalapa_result } = await KalapaEkyc.start(sessionId, flow, config);
+// kalapa_result is already a KalapaResult instance
 ```
 
+> **Security note:** `KalapaResult` contains sensitive personal data — CCCD number, date of birth, MRZ, and a base64 face image from the NFC chip. Do **not** log these fields directly. Use `result.id_number.replace(/.(?=.{4})/g, '*')` or equivalent masking before any logging. Do not store `nfc_data.face_image` unless legally required and properly secured.
+
 #### Core Properties
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `decision` | DecisionType | Decision result: `"APPROVED"`, `"MANUAL"`, `"REJECTED"`, or `"UNKNOWN"` |
-| `selfie_data` | SelfieData | Face matching results |
-| `nfc_data` | NfcData | NFC chip data |
+| `decision` | `DecisionType` | `"APPROVED"`, `"MANUAL"`, `"REJECTED"`, or `"UNKNOWN"` |
 | `session` | string | Session JWT token |
+| `selfie_data` | `SelfieData` | Face matching results |
+| `nfc_data` | `NfcData` | NFC chip data |
+| `mrz_data` | `MrzData \| null` | Parsed MRZ fields |
+| `qr_code` | `QrCode \| null` | QR code data from document |
 | `rawResult` | any | Original unprocessed response |
 
 #### Root-Level Personal Information
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `name` | string | Full name from the verification result |
+| `name` | string | Full name |
 | `id_number` | string | ID card number |
 | `birthday` | string | Birth date |
-| `gender` | string | Gender information |
-| `country` | string | Country information |
+| `gender` | string | Gender |
+| `country` | string | Country |
 | `national` | string | Nationality |
-| `ethnicity` | string | Ethnicity information |
-| `religion` | string | Religious information |
-| `features` | string | Personal identification marks or features |
+| `ethnicity` | string | Ethnicity |
+| `religion` | string | Religion |
+| `features` | string | Personal identification marks |
 | `poi` | string | Place of issue |
-
-#### Date Information
-
-| Property | Type | Description |
-|----------|------|-------------|
 | `doe` | string | Date of expiry |
 | `doi` | string | Date of issuance |
-
-#### Address Information
-
-| Property | Type | Description |
-|----------|------|-------------|
 | `home` | string | Home address (full text) |
-| `home_entities` | AddressEntities | Parsed home address entities (district, ward, province, unknown) |
+| `home_entities` | `AddressEntities` | Parsed home address |
 | `resident` | string | Residential address (full text) |
-| `resident_entities` | AddressEntities | Parsed residential address entities (district, ward, province, unknown) |
-
-#### Document Data
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `mrz_data` | MrzData \| null | Machine Readable Zone data with parsed fields |
-| `qr_code` | QrCode \| null | QR code data from document |
+| `resident_entities` | `AddressEntities` | Parsed residential address |
 | `type` | string | Document type |
 
 ---
 
 ### SelfieData Object
 
-#### Properties
-
 | Property | Type | Description |
 |----------|------|-------------|
-| `is_matched` | boolean | Face matching result |
-| `matching_score` | number | Matching confidence score (0-100) |
-
-#### Usage Example
-
-```typescript
-if (result.selfie_data.is_matched) {
-    console.log(`Face matched with ${result.selfie_data.matching_score}% confidence`);
-}
-```
+| `is_matched` | boolean | Whether face matched the document |
+| `matching_score` | number | Matching confidence score (0–100) |
 
 ---
 
 ### NfcData Object
 
+> **Security note:** `face_image` is a base64-encoded portrait from the NFC chip. Treat it as biometric data — do not log, cache, or transmit without explicit user consent and appropriate security controls.
+
 #### Personal Information
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `name` | string | Full name from NFC chip |
+| `name` | string | Full name |
 | `id_number` | string | ID card number |
 | `old_id_number` | string | Previous ID number (if any) |
-| `date_of_birth` | string | Birth date in DD/MM/YYYY format |
-| `date_of_expiry` | string | ID expiry date in DD/MM/YYYY format |
-| `date_of_issuance` | string | ID issuance date in DD/MM/YYYY format |
-| `gender` | string | Gender information |
+| `date_of_birth` | string | Birth date (DD/MM/YYYY) |
+| `date_of_expiry` | string | Expiry date (DD/MM/YYYY) |
+| `date_of_issuance` | string | Issuance date (DD/MM/YYYY) |
+| `gender` | string | Gender |
 | `nationality` | string | Nationality |
-| `nation` | string | Nation/ethnicity information |
+| `nation` | string | Nation/ethnicity |
 
 #### Address Information
 
@@ -431,22 +437,15 @@ if (result.selfie_data.is_matched) {
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `religion` | string | Religious information |
-| `personal_identification` | string | Personal identification marks or features |
-
-#### Technical Data
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `face_image` | string | Base64 encoded face image from NFC chip |
-| `mrz` | string | Machine Readable Zone data (raw string) |
+| `religion` | string | Religion |
+| `personal_identification` | string | Personal identification marks |
+| `face_image` | string | Base64 face image from NFC chip — handle as biometric data |
+| `mrz` | string | Raw MRZ string |
 
 ---
 
 ### AddressEntities Object
 
-Represents parsed address components:
-
 | Property | Type | Description |
 |----------|------|-------------|
 | `district` | string | District name |
@@ -458,48 +457,27 @@ Represents parsed address components:
 
 ### MrzData Object
 
-Contains MRZ (Machine Readable Zone) information:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `data` | MrzDataFields \| undefined | Parsed MRZ fields |
-| `error` | MrzDataError \| undefined | Error information if parsing failed |
-
-#### MrzDataFields
-
 | Property | Type | Description |
 |----------|------|-------------|
-| `birthday` | string \| undefined | Birth date from MRZ |
-| `doe` | string \| undefined | Date of expiry from MRZ |
-| `gender` | string \| undefined | Gender from MRZ |
-| `id_number` | string \| undefined | ID number from MRZ |
-| `name` | string \| undefined | Name from MRZ |
-| `raw_mrz` | string \| undefined | Raw MRZ string |
-
-#### MrzDataError
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `code` | number | Error code |
-| `message` | string | Error message |
+| `data.fields.birthday` | string \| undefined | Birth date from MRZ |
+| `data.fields.doe` | string \| undefined | Date of expiry from MRZ |
+| `data.fields.gender` | string \| undefined | Gender from MRZ |
+| `data.fields.id_number` | string \| undefined | ID number from MRZ |
+| `data.fields.name` | string \| undefined | Name from MRZ |
+| `data.raw_mrz` | string \| undefined | Raw MRZ string |
+| `error.code` | number \| undefined | Error code if parsing failed |
+| `error.message` | string \| undefined | Error message if parsing failed |
 
 ---
 
 ### QrCode Object
 
-Contains QR code information:
-
 | Property | Type | Description |
 |----------|------|-------------|
-| `data` | QrCodeData \| undefined | Decoded QR code data |
-| `error` | { code: number, message: string } \| undefined | Error information if decoding failed |
-
-#### QrCodeData
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `decoded_text` | string \| undefined | Decoded QR code text |
-| `stage` | number \| undefined | Processing stage |
+| `data.decoded_text` | string \| undefined | Decoded QR code text |
+| `data.stage` | number \| undefined | Processing stage |
+| `error.code` | number \| undefined | Error code if decoding failed |
+| `error.message` | string \| undefined | Error message if decoding failed |
 
 ---
 
@@ -509,92 +487,112 @@ Contains QR code information:
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `isApproved()` | boolean | Returns `true` if decision is `"APPROVED"` |
-| `isManualReview()` | boolean | Returns `true` if decision is `"MANUAL"` |
-| `isRejected()` | boolean | Returns `true` if decision is `"REJECTED"` |
+| `isApproved()` | boolean | `true` if decision is `"APPROVED"` |
+| `isManualReview()` | boolean | `true` if decision is `"MANUAL"` |
+| `isRejected()` | boolean | `true` if decision is `"REJECTED"` |
 
 ### Face Matching Methods
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `isFaceMatched()` | boolean | Returns `true` if face matched successfully |
-| `getFaceMatchingScore()` | number | Returns face matching confidence score |
+| `isFaceMatched()` | boolean | `true` if face matched successfully |
+| `getFaceMatchingScore()` | number | Face matching confidence score |
 
 ### Formatted Getters
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `getDisplayName()` | string | Returns formatted name or `"N/A"` if empty |
-| `getIdNumber()` | string | Returns formatted ID number or `"N/A"` if empty |
-| `getDateOfBirth()` | string | Returns formatted birth date or `"N/A"` if empty |
-| `getFaceImage()` | string | Returns base64 face image from NFC chip |
+| `getDisplayName()` | string | Name from `nfc_data`, or `"N/A"` |
+| `getIdNumber()` | string | ID number from `nfc_data`, or `"N/A"` |
+| `getDateOfBirth()` | string | Birth date from `nfc_data`, or `"N/A"` |
+| `getFaceImage()` | string | Base64 face image from NFC chip |
 
 ### Utility Methods
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `toJSON()` | object | Returns clean object for storage/transmission |
-| `fromRawResult(rawResult)` | KalapaResult | Static method to create KalapaResult from raw response |
+| `toJSON()` | object | Plain object suitable for storage or network transmission |
+| `fromRawResult(raw)` | KalapaResult | Static factory — creates a `KalapaResult` from a raw object |
 
 ---
 
 ## Complete Usage Example
 
 ```typescript
-import KalapaEkyc, { KalapaResult } from 'react-native-kalapa-ekyc';
+import KalapaEkyc, { KalapaResult, KalapaEkycConfig, KalapaEkycFlow } from 'react-native-kalapa-ekyc';
+
+const runEkyc = async (sessionId: string) => {
+    const config: KalapaEkycConfig = {
+        domain: 'https://ekyc-sdk.kalapa.vn',
+        language: 'vi',
+        liveness_version: 3,
+        with_confirm_screen: true,
+        allow_mrz_rescan_on_nfc_mismatch: true,
+    };
+
+    const flow: KalapaEkycFlow = 'nfc_ekyc';
 
-const handleEkyc = async () => {
     try {
-        const rawResult = await KalapaEkyc.start(sessionId, "nfc_only", configInfo);
-        const result = KalapaResult.fromRawResult(rawResult);
-        
-        // Check decision
+        const { kalapa_result: result } = await KalapaEkyc.start(sessionId, flow, config);
+
+        // Decision
         if (result.isApproved()) {
-            console.log("eKYC Approved");
+            console.log('Approved');
         } else if (result.isManualReview()) {
-            console.log("Manual review required");
+            console.log('Manual review required');
+        } else if (result.isRejected()) {
+            console.log('Rejected');
         }
-        
-        // Check face matching
+
+        // Face matching
         if (result.isFaceMatched()) {
-            console.log(`Face matched: ${result.getFaceMatchingScore()}%`);
+            console.log(`Face matched — score: ${result.getFaceMatchingScore()}`);
         }
-        
-        // Access root-level data
-        console.log(`Name: ${result.name}`);
-        console.log(`ID Number: ${result.id_number}`);
-        console.log(`Birthday: ${result.birthday}`);
-        
-        // Access NFC data
-        const userData = {
-            name: result.nfc_data.name,
-            idNumber: result.nfc_data.id_number,
-            birthDate: result.nfc_data.date_of_birth,
-            faceImage: result.nfc_data.face_image
-        };
-        
-        // Access address entities
+
+        // Address entities
         if (result.home_entities) {
-            console.log(`Home: ${result.home_entities.province}, ${result.home_entities.district}`);
+            const { province, district, ward } = result.home_entities;
+            console.log(`Home: ${ward}, ${district}, ${province}`);
         }
-        
-        // Access MRZ data if available
-        if (result.mrz_data?.data) {
-            console.log(`MRZ Name: ${result.mrz_data.data.name}`);
-            console.log(`Raw MRZ: ${result.mrz_data.data.raw_mrz}`);
+
+        // MRZ data
+        if (result.mrz_data?.data?.fields) {
+            const { id_number, name } = result.mrz_data.data.fields;
+            console.log(`MRZ parsed — name: ${name}`); // avoid logging id_number directly
         }
-        
-        // Access QR code data if available
-        if (result.qr_code?.data) {
-            console.log(`QR Code: ${result.qr_code.data.decoded_text}`);
+
+        // QR code data
+        if (result.qr_code?.data?.decoded_text) {
+            console.log('QR decoded');
+        }
+
+        // Export for backend — avoid logging the full object as it contains PII
+        const payload = result.toJSON();
+        await submitToBackend(payload);
+
+    } catch (error: any) {
+        switch (error.code) {
+            case 'EXPIRED':
+                showAlert('Session expired', 'Please start over.');
+                break;
+            case 'CANCELED':
+                // User backed out — no UI needed
+                break;
+            case 'PERMISSION_DENIED':
+                showAlert('Permission required', 'Enable camera and NFC in Settings.');
+                break;
+            case 'DEVICE_NOT_ACCEPTABLE':
+                showAlert('Unsupported device', 'Please use a physical device.');
+                break;
+            case 'NFC_NOT_MATCH':
+                showAlert('NFC mismatch', 'Please rescan your document.');
+                break;
+            case 'ACTIVITY_NULL':
+                // Android: app was backgrounded — ask user to retry
+                break;
+            default:
+                showAlert('Error', error.message ?? 'An unexpected error occurred.');
         }
-        
-        // Export to JSON for storage/transmission
-        const jsonData = result.toJSON();
-        await saveUserData(jsonData);
-        
-    } catch (error) {
-        handleEkycError(error);
     }
 };
 ```
@@ -603,13 +601,13 @@ const handleEkyc = async () => {
 
 ## Summary
 
-The Kalapa eKYC React Native SDK provides comprehensive identity verification with document scanning, face matching, and NFC chip reading capabilities. Key features include:
+The Kalapa eKYC React Native SDK provides identity verification with document scanning, face matching, and NFC chip reading. Key features:
 
-- Three flexible flow types for different verification needs
-- Customizable UI with color and language options
-- Multiple liveness detection versions
-- Type-safe result objects with convenience methods
-- Robust error handling with detailed error codes
-- Support for pre-filled data to skip certain steps
+- Three flexible flow types (`ekyc`, `nfc_ekyc`, `nfc_only`)
+- Fully typed TypeScript API — `KalapaEkycConfig`, `KalapaEkycFlow`, `KalapaEkycErrorCode`
+- Customizable UI (colors, language, confirm screen)
+- Three liveness detection versions
+- Type-safe `KalapaResult` with convenience methods
+- Unified error codes across Android and iOS
 
-For API documentation and session creation, refer to the [Kalapa API documentation](https://kalapa-no.notion.site/eKYC-API-SDK-document-2a2a4ccfa1184a789cb4513fade351e4?pvs=74)
+For API documentation and session creation, refer to the [Kalapa API documentation](https://kalapa-no.notion.site/eKYC-API-SDK-document-2a2a4ccfa1184a789cb4513fade351e4?pvs=74).